From 4d859f78281a6a28c5fadf07c44cbd8d5e0e87ea Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Wed, 28 Dec 2022 17:11:35 -0600 Subject: [PATCH] Add some docs on "Fabric Basics" --- docs/conf.py | 7 ++ docs/deploy/fabric.rst | 154 ++++++++++++++++++++++++++++++++++++++- docs/deploy/overview.rst | 17 ++++- 3 files changed, 174 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index eb36601..fb99434 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,6 +34,7 @@ author = 'Lance Edgar' # ones. extensions = [ 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', ] intersphinx_mapping = { @@ -61,3 +62,9 @@ html_theme = 'alabaster' # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] + + +# -- Lance extra stuff ------------------------------------------------------- + +# allow todo entries to show up +todo_include_todos = True diff --git a/docs/deploy/fabric.rst b/docs/deploy/fabric.rst index bca2744..79b65ed 100644 --- a/docs/deploy/fabric.rst +++ b/docs/deploy/fabric.rst @@ -1,5 +1,153 @@ -Fabric -====== +Fabric Basics +============= -TODO +`Fabric`_ is a Python package which may be used along with SSH to run +commands on (and copy files to) a target machine, among other things. + +.. _Fabric: https://www.fabfile.org/ + +The idea is to install Fabric (and related things) to *your* local/dev +machine, and from there you can run Fabric commands as needed to build +out various other machines. Fabric will connect to each machine over +SSH and then execute shell commands, copy files etc. + +The target machine need not run any special service for this to work. +It's just like you connected to the target machine via SSH and then +ran commands manually, only this way is (ideally) automated and +self-documenting. + + +Supported Platforms +------------------- + +There are two "sides" to the equation, which must be addressed separately. + +Your *local* (e.g. dev) machine is where you'll run Fabric itself. +This machine must have Python 3 installed, and must be able to make +SSH client connections to other machines. + +.. todo:: + I *believe* it should be possible to do this on Windows, but I've + not tried as I only use Linux desktop. + + Should confirm if it works on Windows; maybe document setup. + +The *target* machine however is in all cases assumed to be Linux, +either Debian or Ubuntu. It must run a SSH service. + +.. note:: + Fabric supports more target platforms than just Debian/Ubuntu; most + likely anything with SSH would work. But within the Rattail + Project those are the only 2 being used in production. + + +Note about Versions +------------------- + +TL;DR - we use ``fabric2`` instead of just ``fabric``, to be explicit + +Fabric v1 was created when Python 2 was prevalent. Later on, Python 3 +became prevalent, and Fabric v2 came out to support that. + +Fabric v2 is a total rewrite and not compatible with v1. If you're +just getting started you'll use only v2 and will not need to know +about v1. + +But for historical reasons, the Rattail Project still supports both +versions of Fabric. + +Because of this background, and to be extra clear *which* version of +Fabric is in use, the Rattail Project uses the name ``fabric2`` when +referencing Fabric v2 in code etc. + +For more on this see the following Fabric docs: + +* https://www.fabfile.org/installing.html#installing-as-fabric2 +* https://www.fabfile.org/upgrading.html#running-both-fabric-versions-simultaneously + + +The ``fab2`` command +-------------------- + +When using Fabric to operate on a target machine, you will - on *your* +(local) machine - run one or more ``fab2`` commands. + +Each ``fab2`` command specifies a particular task, which is defined in +your ``fabfile.py`` (see below). + +The command also specifies which machine it should act on. Fabric +then will connect to the machine via SSH, and execute the task logic +on the target machine. + +For example, to run the ``bootstrap_all`` task on "myserver" might be: + +.. code-block:: sh + + fab2 -e -H myserver.example.com bootstrap-all + +Note that even though the task is *actually* (in Python) named +``bootstrap_all``, it must be specified with hyphen as +``bootstrap-all`` on the ``fab2`` command line. + +Also note the ``-e`` (``--echo``) flag which causes Fabric to emit (to +local STDOUT) the full command being ran on the target machine, as it +goes along. (Most tasks execute several commands on the target +machine, so this can be helpful to make sense of output.) + + +The "fabfile" +------------- + +Fabric is rather flexible but here in the Rattail Project we'll set +some guidelines for usage, for simplicity's sake. + +When running the ``fab2`` command, there should be a file named +``fabfile.py`` in the current directory. + +This "fabfile" will contain a number of "tasks" - each of which may +contain multiple commands to be ran on the target machine, etc. + +In our context, normally one "fabfile" contains all task logic for +building out a particular machine. + +For more on how Fabric locates the fabfile (and therefore, tasks), see +https://docs.fabfile.org/en/stable/cli.html#seeking-loading-tasks + +A simple yet complete ``fabfile.py`` example:: + + from fabric2 import task + + @task + def hello_world(c): + + # nb. this runs locally on *your* machine + print("hello world") + + # nb. this runs on target machine + c.run('bash -c "echo my name is `whoami`"') + +This contains one task, but as you can see does *not* specify which +machine it targets. You always must specify that yourself when +running ``fab2`` commands. + + +rattail-fabric2 +--------------- + +Rattail offers some utilitiy functions for use with Fabric, in +`rattail-fabric2`_. + +.. _rattail-fabric2: https://kallithea.rattailproject.org/rattail-project/rattail-fabric2/ + + +The "machine bundle" +-------------------- + +The general idea then, is for you to create and maintain a "fabric +bundle" for each machine you wish to manage in this way. Bundles are +described elsewhere, but the gist is, they contain all necessary +commands and config files to build out the machine. + +.. todo:: + Link to fabric bundle docs after they are made. diff --git a/docs/deploy/overview.rst b/docs/deploy/overview.rst index 45595c5..2853430 100644 --- a/docs/deploy/overview.rst +++ b/docs/deploy/overview.rst @@ -2,4 +2,19 @@ Overview ======== -TODO +Deployment refers to the complete setup (install + configuration) of a +Rattail app, on a production or other server. + +When deploying the app you essentially have 3 options: + +* deploy manually +* deploy via Fabric +* deploy via some other system (Ansible, Chef, Puppet etc.) + +The "official" way is to use Fabric, hence that will be documented +here. It is preferred over manual setup because it is +automated/repeatable and self-documenting etc. + +.. note:: + The use of Fabric to deploy only supports Linux as the app/target + server (so far?).