mirror of https://github.com/mitsuhiko/flask.git
Armin Ronacher
15 years ago
5 changed files with 219 additions and 2 deletions
@ -0,0 +1,196 @@
|
||||
.. _fabric-deployment: |
||||
|
||||
Deploying with Fabric |
||||
===================== |
||||
|
||||
`Fabric`_ is a tool for Python similar to Makefiles but with the ability |
||||
to execute commands on a remote server. In combination with a properly |
||||
set up Python package (:ref:`larger-applications`) and a good concept for |
||||
configurations (:ref:`config`) it is very easy to deploy Flask |
||||
applications to external servers. |
||||
|
||||
Before we get started, here a quick checklist of things we have to ensure |
||||
upfront: |
||||
|
||||
- Fabric 1.0 has to be installed locally. This tutorial assumes the |
||||
latest version of Fabric. |
||||
- The application already has to be a package and requires a working |
||||
`setup.py` file (:ref:`distribute-deployment`). |
||||
- In the following example we are using `mod_wsgi` for the remote |
||||
servers. You can of course use your own favourite server there, but |
||||
for this example we chose Apache + `mod_wsgi` because it's very easy |
||||
to setup and has a simple way to reload applications without root |
||||
access. |
||||
|
||||
Creating the first Fabfile |
||||
-------------------------- |
||||
|
||||
A fabfile is what controls what Fabric executes. It is named `fabfile.py` |
||||
and executed by the `fab` command. All the functions defined in that file |
||||
will show up as `fab` subcommands. They are executed on one or more |
||||
hosts. These hosts can be defined either in the fabfile or on the command |
||||
line. In this case we will add them to the fabfile. |
||||
|
||||
This is a basic first example that has the ability to upload the current |
||||
sourcecode to the server and install it into a already existing |
||||
virtual environment:: |
||||
|
||||
from fabric.api import * |
||||
|
||||
# the user to use for the remote commands |
||||
env.user = 'appuser' |
||||
# the servers where the commands are executed |
||||
env.hosts = ['server1.example.com', 'server2.example.com'] |
||||
|
||||
def pack(): |
||||
# create a new source distribution as tarball |
||||
local('python setup.py sdist --formats=gztar', capture=False) |
||||
|
||||
def deploy(): |
||||
# figure out the release name and version |
||||
dist = local('python setup.py --fullname').strip() |
||||
# upload the source tarball to the temporary folder on the server |
||||
put('sdist/%s.tar.gz' % dist, '/tmp/') |
||||
# create a place where we can unzip the tarball, then enter |
||||
# that directory and unzip it |
||||
run('mkdir yourapplication') |
||||
with cd('/tmp/yourapplication'): |
||||
run('tar xzf /tmp/yourapplication.tar.gz') |
||||
# now setup the package with our virtual environment's |
||||
# python interpreter |
||||
run('/var/www/yourapplication/env/bin/python setup.py install') |
||||
# now that all is set up, delete the folder again |
||||
run('rm -rf /tmp/yourapplication /tmp/yourapplication.tar.gz') |
||||
# and finally touch the .wsgi file so that mod_wsgi triggers |
||||
# a reload of the application |
||||
run('touch /var/www/yourapplication.wsgi') |
||||
|
||||
The example above is well documented and should be straightforward. Here |
||||
a recap of the most common commands fabric provides: |
||||
|
||||
- `run` - executes a command on a remote server |
||||
- `local` - executes a command on the local machine |
||||
- `put` - uploads a file to the remote server |
||||
- `cd` - changes the directory on the serverside. This has to be used |
||||
in combination with the `with` statement. |
||||
|
||||
Running Fabfiles |
||||
---------------- |
||||
|
||||
Now how do you execute that fabfile? You use the `fab` command. To |
||||
deploy the current version of the code on the remote server you would use |
||||
this command:: |
||||
|
||||
$ fab pack deploy |
||||
|
||||
However this requires that our server already has the |
||||
``/var/www/yourapplication`` folder created and |
||||
``/var/www/yourapplication/env`` to be a virtual environment. Furthermore |
||||
are we not creating the configuration or `.wsgi` file on the server. So |
||||
how do we bootstrap a new server into our infrastructure? |
||||
|
||||
This now depends on the number of servers we want to set up. If we just |
||||
have one application server (which the majority of applications will |
||||
have), creating a command in the fabfile for this is overkill. But |
||||
obviously you can do that. In that case you would probably call it |
||||
`setup` or `bootstrap` and then pass the servername explicitly on the |
||||
command line:: |
||||
|
||||
$ fab -H newserver.example.com bootstrap |
||||
|
||||
To setup a new server you would roughly do these steps: |
||||
|
||||
1. Create the directory structure in ``/var/www``:: |
||||
|
||||
$ mkdir /var/www/yourapplication |
||||
$ cd /var/www/yourapplication |
||||
$ virtualenv --distribute env |
||||
|
||||
2. Upload a new `application.wsgi` file to the server and the |
||||
configuration file for the application (eg: `application.cfg`) |
||||
|
||||
3. Create a new Apache config for `yourapplication` and activate it. |
||||
Make sure to activate watching for changes of the `.wsgi` file so |
||||
that we can automatically reload the application by touching it. |
||||
(See :ref:`mod_wsgi-deployment` for more information) |
||||
|
||||
So now the question is, where do the `application.wsgi` and |
||||
`application.cfg` files come from? |
||||
|
||||
The WSGI File |
||||
------------- |
||||
|
||||
The WSGI file has to import the application and also to set an environment |
||||
variable so that the application knows where to look for the config. This |
||||
is a short example that does exactly that:: |
||||
|
||||
import os |
||||
os.environ['YOURAPPLICATION_CONFIG'] = '/var/www/yourapplication/application.cfg' |
||||
from yourapplication import app |
||||
|
||||
The application itself then has to initialize itself like this to look for |
||||
the config at that environment variable:: |
||||
|
||||
app = Flask(__name__) |
||||
app.config.from_object('yourapplication.default_config') |
||||
app.config.from_envvar('YOURAPPLICATION_CONFIG') |
||||
|
||||
This approach is explained in detail in the :ref:`config` section of the |
||||
documentation. |
||||
|
||||
The Configuration File |
||||
---------------------- |
||||
|
||||
Now as mentioned above, the application will find the correct |
||||
configuration file by looking up the `YOURAPPLICATION_CONFIG` environment |
||||
variable. So we have to put the configuration in a place where the |
||||
application will able to find it. Configuration files have the unfriendly |
||||
quality of being different on all computers, so you do not version them |
||||
usually. |
||||
|
||||
A popular approach is to store configuration files for different servers |
||||
in a separate version control repository and check them out on all |
||||
servers. Then symlink the file that is active for the server into the |
||||
location where it's expected (eg: ``/var/www/yourapplication``). |
||||
|
||||
Either way, in our case here we only expect one or two servers and we can |
||||
upload them ahead of time by hand. |
||||
|
||||
First Deployment |
||||
---------------- |
||||
|
||||
Now we can do our first deployment. We have set up the servers so that |
||||
they have their virtual environments and activated apache configs. Now we |
||||
can pack up the application and deploy it:: |
||||
|
||||
$ fab pack deploy |
||||
|
||||
Fabric will now connect to all servers and run the commands as written |
||||
down in the fabfile. First it will execute pack so that we have our |
||||
tarball ready and then it will execute deploy and upload the source code |
||||
to all servers and install it there. Thanks to the `setup.py` file we |
||||
will automatically pull in the required libraries into our virtual |
||||
environment. |
||||
|
||||
Next Steps |
||||
---------- |
||||
|
||||
From that point onwards there is so much that can be done to make |
||||
deployment actually fun: |
||||
|
||||
- Create a `bootstrap` command that initializes new servers. It could |
||||
initialize a new virtual environment, setup apache appropriately etc. |
||||
- Put configuration files into a separate version control repository |
||||
and symlink the active configs into place. |
||||
- You could also put your application code into a repository and check |
||||
out the latest version on the server and then install. That way you |
||||
can also easily go back to older versions. |
||||
- hook in testing functionality so that you can deploy to an external |
||||
server and run the testsuite. |
||||
|
||||
Working with Fabric is fun and you will notice that it's quite magical to |
||||
type ``fab deploy`` and see your application being deployed automatically |
||||
to one or more remote servers. |
||||
|
||||
|
||||
.. _Fabric: http://fabfile.org/ |
||||
Loading…
Reference in new issue