Skip to content

Commit 207006f

Browse files
rduplainrduplain
committed
Touch up and integrate docs on deploying Flask.
1 parent 5127b8b commit 207006f

File tree

6 files changed

+145
-123
lines changed

6 files changed

+145
-123
lines changed

‎docs/deploying/cgi.rst

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,20 @@
11
CGI
22
===
33

4-
If all other deployment methods do not work, CGI will work for sure. CGI
5-
is supported by all major servers but usually has a less-than-optimal
4+
If all other deployment methods do not work, CGI will work for sure.
5+
CGI is supported by all major servers but usually has a sub-optimal
66
performance.
77

8-
This is also the way you can use a Flask application on Google's
9-
`App Engine`_, there however the execution does happen in a CGI-like
10-
environment. The application's performance is unaffected because of that.
8+
This is also the way you can use a Flask application on Google's `App
9+
Engine`_, where execution happens in a CGI-like environment.
1110

1211
.. admonition:: Watch Out
1312

14-
Please make sure in advance that your ``app.run()`` call you might
15-
have in your application file, is inside an ``if __name__ ==
16-
'__main__':`` or moved to a separate file. Just make sure it's not
17-
called because this will always start a local WSGI server which we do
18-
not want if we deploy that application to CGI / app engine.
19-
20-
.. _App Engine: http://code.google.com/appengine/
13+
Please make sure in advance that any ``app.run()`` calls you might
14+
have in your application file are inside an ``if __name__ ==
15+
'__main__':`` block or moved to a separate file. Just make sure it's
16+
not called because this will always start a local WSGI server which
17+
we do not want if we deploy that application to CGI / app engine.
2118

2219
Creating a `.cgi` file
2320
----------------------
@@ -45,3 +42,5 @@ In Apache for example you can put a like like this into the config:
4542
ScriptAlias /app /path/to/the/application.cgi
4643

4744
For more information consult the documentation of your webserver.
45+
46+
.. _App Engine: http://code.google.com/appengine/

‎docs/deploying/fastcgi.rst

Lines changed: 54 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,22 @@
1+
.. _deploying-fastcgi:
2+
13
FastCGI
24
=======
35

4-
A very popular deployment setup on servers like `lighttpd`_ and `nginx`_
5-
is FastCGI. To use your WSGI application with any of them you will need
6-
a FastCGI server first.
7-
8-
The most popular one is `flup`_ which we will use for this guide. Make
9-
sure to have it installed.
6+
FastCGI is a deployment option on servers like `nginx`_, `lighttpd`_,
7+
and `cherokee`_; see :ref:`deploying-uwsgi` and
8+
:ref:`deploying-other-servers` for other options. To use your WSGI
9+
application with any of them you will need a FastCGI server first. The
10+
most popular one is `flup`_ which we will use for this guide. Make sure
11+
to have it installed to follow along.
1012

1113
.. admonition:: Watch Out
1214

13-
Please make sure in advance that your ``app.run()`` call you might
14-
have in your application file, is inside an ``if __name__ ==
15-
'__main__':`` or moved to a separate file. Just make sure it's not
16-
called because this will always start a local WSGI server which we do
17-
not want if we deploy that application to FastCGI.
15+
Please make sure in advance that any ``app.run()`` calls you might
16+
have in your application file are inside an ``if __name__ ==
17+
'__main__':`` block or moved to a separate file. Just make sure it's
18+
not called because this will always start a local WSGI server which
19+
we do not want if we deploy that application to FastCGI.
1820

1921
Creating a `.fcgi` file
2022
-----------------------
@@ -25,14 +27,14 @@ First you need to create the FastCGI server file. Let's call it
2527
#!/usr/bin/python
2628
from flup.server.fcgi import WSGIServer
2729
from yourapplication import app
28-
30+
2931
if __name__ == '__main__':
3032
WSGIServer(app).run()
3133

3234
This is enough for Apache to work, however nginx and older versions of
33-
lighttpd need a socket to be explicitly passed to communicate with the FastCGI
34-
server. For that to work you need to pass the path to the socket to the
35-
:class:`~flup.server.fcgi.WSGIServer`::
35+
lighttpd need a socket to be explicitly passed to communicate with the
36+
FastCGI server. For that to work you need to pass the path to the
37+
socket to the :class:`~flup.server.fcgi.WSGIServer`::
3638

3739
WSGIServer(application, bindAddress='/path/to/fcgi.sock').run()
3840

@@ -72,22 +74,23 @@ A basic FastCGI configuration for lighttpd looks like that::
7274
"^(/static.*)$" => "$1",
7375
"^(/.*)$" => "/yourapplication.fcgi$1"
7476

75-
Remember to enable the FastCGI, alias and rewrite modules. This configuration
76-
binds the application to `/yourapplication`. If you want the application to
77-
work in the URL root you have to work around a lighttpd bug with the
77+
Remember to enable the FastCGI, alias and rewrite modules. This
78+
configuration binds the application to `/yourapplication`. If you want
79+
the application to work in the URL root you have to work around a
80+
lighttpd bug with the
7881
:class:`~werkzeug.contrib.fixers.LighttpdCGIRootFix` middleware.
7982

8083
Make sure to apply it only if you are mounting the application the URL
81-
root. Also, see the Lighty docs for more information on `FastCGI and Python
82-
<http://redmine.lighttpd.net/wiki/lighttpd/Docs:ModFastCGI>`_ (note that
83-
explicitly passing a socket to run() is no longer necessary).
84+
root. Also, see the Lighty docs for more information on `FastCGI and
85+
Python <http://redmine.lighttpd.net/wiki/lighttpd/Docs:ModFastCGI>`_
86+
(note that explicitly passing a socket to run() is no longer necessary).
8487

8588

8689
Configuring nginx
8790
-----------------
8891

89-
Installing FastCGI applications on nginx is a bit different because by default
90-
no FastCGI parameters are forwarded.
92+
Installing FastCGI applications on nginx is a bit different because by
93+
default no FastCGI parameters are forwarded.
9194

9295
A basic flask FastCGI configuration for nginx looks like this::
9396

@@ -101,9 +104,9 @@ A basic flask FastCGI configuration for nginx looks like this::
101104
fastcgi_pass unix:/tmp/yourapplication-fcgi.sock;
102105
}
103106

104-
This configuration binds the application to `/yourapplication`. If you want
105-
to have it in the URL root it's a bit simpler because you don't have to figure
106-
out how to calculate `PATH_INFO` and `SCRIPT_NAME`::
107+
This configuration binds the application to `/yourapplication`. If you
108+
want to have it in the URL root it's a bit simpler because you don't
109+
have to figure out how to calculate `PATH_INFO` and `SCRIPT_NAME`::
107110

108111
location / { try_files $uri @yourapplication; }
109112
location @yourapplication {
@@ -113,24 +116,32 @@ out how to calculate `PATH_INFO` and `SCRIPT_NAME`::
113116
fastcgi_pass unix:/tmp/yourapplication-fcgi.sock;
114117
}
115118

116-
Since Nginx doesn't load FastCGI apps, you have to do it by yourself. You
117-
can either write an `init.d` script for that or execute it inside a screen
118-
session::
119+
Running FastCGI Processes
120+
-------------------------
121+
122+
Since Nginx and others do not load FastCGI apps, you have to do it by
123+
yourself. `Supervisor can manage FastCGI processes.
124+
<http://supervisord.org/configuration.html#fcgi-program-x-section-settings>`_
125+
You can look around for other FastCGI process managers or write a script
126+
to run your `.fcgi` file at boot, e.g. using a SysV ``init.d`` script.
127+
For a temporary solution, you can always run the ``.fcgi`` script inside
128+
GNU screen. See ``man screen`` for details, and note that this is a
129+
manual solution which does not persist across system restart::
119130

120131
$ screen
121132
$ /var/www/yourapplication/yourapplication.fcgi
122133

123134
Debugging
124135
---------
125136

126-
FastCGI deployments tend to be hard to debug on most webservers. Very often the
127-
only thing the server log tells you is something along the lines of "premature
128-
end of headers". In order to debug the application the only thing that can
129-
really give you ideas why it breaks is switching to the correct user and
130-
executing the application by hand.
137+
FastCGI deployments tend to be hard to debug on most webservers. Very
138+
often the only thing the server log tells you is something along the
139+
lines of "premature end of headers". In order to debug the application
140+
the only thing that can really give you ideas why it breaks is switching
141+
to the correct user and executing the application by hand.
131142

132-
This example assumes your application is called `application.fcgi` and that your
133-
webserver user is `www-data`::
143+
This example assumes your application is called `application.fcgi` and
144+
that your webserver user is `www-data`::
134145

135146
$ su www-data
136147
$ cd /var/www/yourapplication
@@ -139,14 +150,15 @@ webserver user is `www-data`::
139150
File "yourapplication.fcgi", line 4, in <module>
140151
ImportError: No module named yourapplication
141152

142-
In this case the error seems to be "yourapplication" not being on the python
143-
path. Common problems are:
153+
In this case the error seems to be "yourapplication" not being on the
154+
python path. Common problems are:
144155

145-
- relative paths being used. Don't rely on the current working directory
146-
- the code depending on environment variables that are not set by the
156+
- Relative paths being used. Don't rely on the current working directory
157+
- The code depending on environment variables that are not set by the
147158
web server.
148-
- different python interpreters being used.
159+
- Different python interpreters being used.
149160

150-
.. _lighttpd: http://www.lighttpd.net/
151161
.. _nginx: http://nginx.org/
162+
.. _lighttpd: http://www.lighttpd.net/
163+
.. _cherokee: http://www.cherokee-project.com/
152164
.. _flup: http://trac.saddi.com/flup

‎docs/deploying/index.rst

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
Deployment Options
22
==================
33

4-
Depending on what you have available there are multiple ways to run Flask
5-
applications. A very common method is to use the builtin server during
6-
development and maybe behind a proxy for simple applications, but there
7-
are more options available.
4+
Depending on what you have available there are multiple ways to run
5+
Flask applications. You can use the builtin server during development,
6+
but you should use a full deployment option for production applications.
7+
(Do not use the builtin development server in production.) Several
8+
options are available and documented here.
89

9-
If you have a different WSGI server look up the server documentation about
10-
how to use a WSGI app with it. Just remember that your application object
11-
is the actual WSGI application.
10+
If you have a different WSGI server look up the server documentation
11+
about how to use a WSGI app with it. Just remember that your
12+
:class:`Flask` application object is the actual WSGI application.
1213

1314
.. toctree::
1415
:maxdepth: 2

‎docs/deploying/mod_wsgi.rst

Lines changed: 35 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -3,35 +3,34 @@
33
mod_wsgi (Apache)
44
=================
55

6-
If you are using the `Apache`_ webserver you should consider using `mod_wsgi`_.
6+
If you are using the `Apache`_ webserver, consider using `mod_wsgi`_.
77

88
.. admonition:: Watch Out
99

10-
Please make sure in advance that your ``app.run()`` call you might
11-
have in your application file, is inside an ``if __name__ ==
12-
'__main__':`` or moved to a separate file. Just make sure it's not
13-
called because this will always start a local WSGI server which we do
14-
not want if we deploy that application to mod_wsgi.
10+
Please make sure in advance that any ``app.run()`` calls you might
11+
have in your application file are inside an ``if __name__ ==
12+
'__main__':`` block or moved to a separate file. Just make sure it's
13+
not called because this will always start a local WSGI server which
14+
we do not want if we deploy that application to mod_wsgi.
1515

1616
.. _Apache: http://httpd.apache.org/
1717

1818
Installing `mod_wsgi`
1919
---------------------
2020

21-
If you don't have `mod_wsgi` installed yet you have to either install it using
22-
a package manager or compile it yourself.
21+
If you don't have `mod_wsgi` installed yet you have to either install it
22+
using a package manager or compile it yourself. The mod_wsgi
23+
`installation instructions`_ cover source installations on UNIX systems.
2324

24-
The mod_wsgi `installation instructions`_ cover source installations on UNIX
25-
systems.
26-
27-
If you are using Ubuntu/Debian you can apt-get it and activate it as follows:
25+
If you are using Ubuntu/Debian you can apt-get it and activate it as
26+
follows:
2827

2928
.. sourcecode:: text
3029

3130
# apt-get install libapache2-mod-wsgi
3231

33-
On FreeBSD install `mod_wsgi` by compiling the `www/mod_wsgi` port or by using
34-
pkg_add:
32+
On FreeBSD install `mod_wsgi` by compiling the `www/mod_wsgi` port or by
33+
using pkg_add:
3534

3635
.. sourcecode:: text
3736

@@ -40,8 +39,8 @@ pkg_add:
4039
If you are using pkgsrc you can install `mod_wsgi` by compiling the
4140
`www/ap2-wsgi` package.
4241

43-
If you encounter segfaulting child processes after the first apache reload you
44-
can safely ignore them. Just restart the server.
42+
If you encounter segfaulting child processes after the first apache
43+
reload you can safely ignore them. Just restart the server.
4544

4645
Creating a `.wsgi` file
4746
-----------------------
@@ -61,14 +60,15 @@ instance you can directly import that one as `application`.
6160
Store that file somewhere that you will find it again (e.g.:
6261
`/var/www/yourapplication`) and make sure that `yourapplication` and all
6362
the libraries that are in use are on the python load path. If you don't
64-
want to install it system wide consider using a `virtual python`_ instance.
63+
want to install it system wide consider using a `virtual python`_
64+
instance.
6565

6666
Configuring Apache
6767
------------------
6868

69-
The last thing you have to do is to create an Apache configuration file for
70-
your application. In this example we are telling `mod_wsgi` to execute the
71-
application under a different user for security reasons:
69+
The last thing you have to do is to create an Apache configuration file
70+
for your application. In this example we are telling `mod_wsgi` to
71+
execute the application under a different user for security reasons:
7272

7373
.. sourcecode:: apache
7474

@@ -100,15 +100,16 @@ If your application does not run, follow this guide to troubleshoot:
100100

101101
**Problem:** application does not run, errorlog shows SystemExit ignored
102102
You have a ``app.run()`` call in your application file that is not
103-
guarded by an ``if __name__ == '__main__':`` condition. Either remove
104-
that :meth:`~flask.Flask.run` call from the file and move it into a
105-
separate `run.py` file or put it into such an if block.
103+
guarded by an ``if __name__ == '__main__':`` condition. Either
104+
remove that :meth:`~flask.Flask.run` call from the file and move it
105+
into a separate `run.py` file or put it into such an if block.
106106

107107
**Problem:** application gives permission errors
108108
Probably caused by your application running as the wrong user. Make
109109
sure the folders the application needs access to have the proper
110-
privileges set and the application runs as the correct user (``user``
111-
and ``group`` parameter to the `WSGIDaemonProcess` directive)
110+
privileges set and the application runs as the correct user
111+
(``user`` and ``group`` parameter to the `WSGIDaemonProcess`
112+
directive)
112113

113114
**Problem:** application dies with an error on print
114115
Keep in mind that mod_wsgi disallows doing anything with
@@ -127,10 +128,10 @@ If your application does not run, follow this guide to troubleshoot:
127128
sys.stdout = sys.stderr
128129

129130
**Problem:** accessing resources gives IO errors
130-
Your application probably is a single .py file you symlinked into the
131-
site-packages folder. Please be aware that this does not work,
132-
instead you either have to put the folder into the pythonpath the file
133-
is stored in, or convert your application into a package.
131+
Your application probably is a single .py file you symlinked into
132+
the site-packages folder. Please be aware that this does not work,
133+
instead you either have to put the folder into the pythonpath the
134+
file is stored in, or convert your application into a package.
134135

135136
The reason for this is that for non-installed packages, the module
136137
filename is used to locate the resources and for symlinks the wrong
@@ -139,9 +140,9 @@ If your application does not run, follow this guide to troubleshoot:
139140
Support for Automatic Reloading
140141
-------------------------------
141142

142-
To help deployment tools you can activate support for automatic reloading.
143-
Whenever something changes the `.wsgi` file, `mod_wsgi` will reload all
144-
the daemon processes for us.
143+
To help deployment tools you can activate support for automatic
144+
reloading. Whenever something changes the `.wsgi` file, `mod_wsgi` will
145+
reload all the daemon processes for us.
145146

146147
For that, just add the following directive to your `Directory` section:
147148

@@ -154,8 +155,8 @@ Working with Virtual Environments
154155

155156
Virtual environments have the advantage that they never install the
156157
required dependencies system wide so you have a better control over what
157-
is used where. If you want to use a virtual environment with mod_wsgi you
158-
have to modify your `.wsgi` file slightly.
158+
is used where. If you want to use a virtual environment with mod_wsgi
159+
you have to modify your `.wsgi` file slightly.
159160

160161
Add the following lines to the top of your `.wsgi` file::
161162

0 commit comments

Comments
 (0)