Add some docs on "Fabric Basics"
This commit is contained in:
Lance Edgar
parent
2cf27b543f
commit
4d859f7828
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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?).
|
||||
|
|
|
|||
Loading…
Reference in a new issue