forked from orbit-oss/flask
Touch up and integrate docs on deploying Flask.
This commit is contained in:
Ron DuPlain
parent
5127b8bd26
commit
207006f4c3
6 changed files with 145 additions and 123 deletions
|
|
@ -1,20 +1,22 @@
|
|||
.. _deploying-fastcgi:
|
||||
|
||||
FastCGI
|
||||
=======
|
||||
|
||||
A very popular deployment setup on servers like `lighttpd`_ and `nginx`_
|
||||
is FastCGI. To use your WSGI application with any of them you will need
|
||||
a FastCGI server first.
|
||||
|
||||
The most popular one is `flup`_ which we will use for this guide. Make
|
||||
sure to have it installed.
|
||||
FastCGI is a deployment option on servers like `nginx`_, `lighttpd`_,
|
||||
and `cherokee`_; see :ref:`deploying-uwsgi` and
|
||||
:ref:`deploying-other-servers` for other options. To use your WSGI
|
||||
application with any of them you will need a FastCGI server first. The
|
||||
most popular one is `flup`_ which we will use for this guide. Make sure
|
||||
to have it installed to follow along.
|
||||
|
||||
.. admonition:: Watch Out
|
||||
|
||||
Please make sure in advance that your ``app.run()`` call you might
|
||||
have in your application file, is inside an ``if __name__ ==
|
||||
'__main__':`` or moved to a separate file. Just make sure it's not
|
||||
called because this will always start a local WSGI server which we do
|
||||
not want if we deploy that application to FastCGI.
|
||||
Please make sure in advance that any ``app.run()`` calls you might
|
||||
have in your application file are inside an ``if __name__ ==
|
||||
'__main__':`` block or moved to a separate file. Just make sure it's
|
||||
not called because this will always start a local WSGI server which
|
||||
we do not want if we deploy that application to FastCGI.
|
||||
|
||||
Creating a `.fcgi` file
|
||||
-----------------------
|
||||
|
|
@ -25,14 +27,14 @@ First you need to create the FastCGI server file. Let's call it
|
|||
#!/usr/bin/python
|
||||
from flup.server.fcgi import WSGIServer
|
||||
from yourapplication import app
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
WSGIServer(app).run()
|
||||
|
||||
This is enough for Apache to work, however nginx and older versions of
|
||||
lighttpd need a socket to be explicitly passed to communicate with the FastCGI
|
||||
server. For that to work you need to pass the path to the socket to the
|
||||
:class:`~flup.server.fcgi.WSGIServer`::
|
||||
lighttpd need a socket to be explicitly passed to communicate with the
|
||||
FastCGI server. For that to work you need to pass the path to the
|
||||
socket to the :class:`~flup.server.fcgi.WSGIServer`::
|
||||
|
||||
WSGIServer(application, bindAddress='/path/to/fcgi.sock').run()
|
||||
|
||||
|
|
@ -72,22 +74,23 @@ A basic FastCGI configuration for lighttpd looks like that::
|
|||
"^(/static.*)$" => "$1",
|
||||
"^(/.*)$" => "/yourapplication.fcgi$1"
|
||||
|
||||
Remember to enable the FastCGI, alias and rewrite modules. This configuration
|
||||
binds the application to `/yourapplication`. If you want the application to
|
||||
work in the URL root you have to work around a lighttpd bug with the
|
||||
Remember to enable the FastCGI, alias and rewrite modules. This
|
||||
configuration binds the application to `/yourapplication`. If you want
|
||||
the application to work in the URL root you have to work around a
|
||||
lighttpd bug with the
|
||||
:class:`~werkzeug.contrib.fixers.LighttpdCGIRootFix` middleware.
|
||||
|
||||
Make sure to apply it only if you are mounting the application the URL
|
||||
root. Also, see the Lighty docs for more information on `FastCGI and Python
|
||||
<http://redmine.lighttpd.net/wiki/lighttpd/Docs:ModFastCGI>`_ (note that
|
||||
explicitly passing a socket to run() is no longer necessary).
|
||||
root. Also, see the Lighty docs for more information on `FastCGI and
|
||||
Python <http://redmine.lighttpd.net/wiki/lighttpd/Docs:ModFastCGI>`_
|
||||
(note that explicitly passing a socket to run() is no longer necessary).
|
||||
|
||||
|
||||
Configuring nginx
|
||||
-----------------
|
||||
|
||||
Installing FastCGI applications on nginx is a bit different because by default
|
||||
no FastCGI parameters are forwarded.
|
||||
Installing FastCGI applications on nginx is a bit different because by
|
||||
default no FastCGI parameters are forwarded.
|
||||
|
||||
A basic flask FastCGI configuration for nginx looks like this::
|
||||
|
||||
|
|
@ -101,9 +104,9 @@ A basic flask FastCGI configuration for nginx looks like this::
|
|||
fastcgi_pass unix:/tmp/yourapplication-fcgi.sock;
|
||||
}
|
||||
|
||||
This configuration binds the application to `/yourapplication`. If you want
|
||||
to have it in the URL root it's a bit simpler because you don't have to figure
|
||||
out how to calculate `PATH_INFO` and `SCRIPT_NAME`::
|
||||
This configuration binds the application to `/yourapplication`. If you
|
||||
want to have it in the URL root it's a bit simpler because you don't
|
||||
have to figure out how to calculate `PATH_INFO` and `SCRIPT_NAME`::
|
||||
|
||||
location / { try_files $uri @yourapplication; }
|
||||
location @yourapplication {
|
||||
|
|
@ -113,9 +116,17 @@ out how to calculate `PATH_INFO` and `SCRIPT_NAME`::
|
|||
fastcgi_pass unix:/tmp/yourapplication-fcgi.sock;
|
||||
}
|
||||
|
||||
Since Nginx doesn't load FastCGI apps, you have to do it by yourself. You
|
||||
can either write an `init.d` script for that or execute it inside a screen
|
||||
session::
|
||||
Running FastCGI Processes
|
||||
-------------------------
|
||||
|
||||
Since Nginx and others do not load FastCGI apps, you have to do it by
|
||||
yourself. `Supervisor can manage FastCGI processes.
|
||||
<http://supervisord.org/configuration.html#fcgi-program-x-section-settings>`_
|
||||
You can look around for other FastCGI process managers or write a script
|
||||
to run your `.fcgi` file at boot, e.g. using a SysV ``init.d`` script.
|
||||
For a temporary solution, you can always run the ``.fcgi`` script inside
|
||||
GNU screen. See ``man screen`` for details, and note that this is a
|
||||
manual solution which does not persist across system restart::
|
||||
|
||||
$ screen
|
||||
$ /var/www/yourapplication/yourapplication.fcgi
|
||||
|
|
@ -123,14 +134,14 @@ session::
|
|||
Debugging
|
||||
---------
|
||||
|
||||
FastCGI deployments tend to be hard to debug on most webservers. Very often the
|
||||
only thing the server log tells you is something along the lines of "premature
|
||||
end of headers". In order to debug the application the only thing that can
|
||||
really give you ideas why it breaks is switching to the correct user and
|
||||
executing the application by hand.
|
||||
FastCGI deployments tend to be hard to debug on most webservers. Very
|
||||
often the only thing the server log tells you is something along the
|
||||
lines of "premature end of headers". In order to debug the application
|
||||
the only thing that can really give you ideas why it breaks is switching
|
||||
to the correct user and executing the application by hand.
|
||||
|
||||
This example assumes your application is called `application.fcgi` and that your
|
||||
webserver user is `www-data`::
|
||||
This example assumes your application is called `application.fcgi` and
|
||||
that your webserver user is `www-data`::
|
||||
|
||||
$ su www-data
|
||||
$ cd /var/www/yourapplication
|
||||
|
|
@ -139,14 +150,15 @@ webserver user is `www-data`::
|
|||
File "yourapplication.fcgi", line 4, in <module>
|
||||
ImportError: No module named yourapplication
|
||||
|
||||
In this case the error seems to be "yourapplication" not being on the python
|
||||
path. Common problems are:
|
||||
In this case the error seems to be "yourapplication" not being on the
|
||||
python path. Common problems are:
|
||||
|
||||
- relative paths being used. Don't rely on the current working directory
|
||||
- the code depending on environment variables that are not set by the
|
||||
- Relative paths being used. Don't rely on the current working directory
|
||||
- The code depending on environment variables that are not set by the
|
||||
web server.
|
||||
- different python interpreters being used.
|
||||
- Different python interpreters being used.
|
||||
|
||||
.. _lighttpd: http://www.lighttpd.net/
|
||||
.. _nginx: http://nginx.org/
|
||||
.. _lighttpd: http://www.lighttpd.net/
|
||||
.. _cherokee: http://www.cherokee-project.com/
|
||||
.. _flup: http://trac.saddi.com/flup
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue