Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: c5e13bc946
Fetching contributors…

Cannot retrieve contributors at this time

file 302 lines (231 sloc) 8.887 kb

Nginx + paster + supervisord

This setup can be accomplished simply and is capable of serving a large amount of traffic. The advantage in deployment is that by using paster, it is not unlike the basic development environment you're probably using on your local machine.

Nginx is a highly optimized HTTP server, very capable of serving static content as well as acting as a proxy between other applications and the outside world. As a proxy, it also has good support for basic load balancing between multiple instances of an application.

Client <---> Nginx [0.0.0.0:80] <---> (static files)
              /|\
               |-------> Paster [localhost:5000]
               `-------> Paster [localhost:5001]

Our target setup is going to be an Nginx server listening on port 80 and load-balancing between 2 Paster processes. It will also serve the static files from our project's directory.

Let's assume a basic project setup:

/home/example/myapp
|
|-- env (your virtualenv)
|
|-- myapp
|   |
|   |-- __init__.py (defining your main entry point)
|   |
|   `-- static (your static files)
|
|-- production.ini
|
`-- supervisord.conf (optional)

Step 1: Configuring Nginx

Nginx needs to be configured as a proxy for your application. An example configuration is shown here:

Note

myapp.conf is actually included into the http {} section of the main nginx.conf file.

The upstream directive sets up a round-robin load-balancer between two processes. The proxy is then configured to pass requests through the balancer with the proxy_pass directive. It's important to investigate the implications of many of the other settings as they are likely application-specific.

The header directives inform our application of the exact deployment setup. They will help the WSGI server configure our environment's SCRIPT_NAME, HTTP_HOST, and the actual IP address of the client.

Step 2: Starting Paster

Warning

Be sure to create a production.ini file to use for deployment that has debugging turned off, including removing the WebError#evalerror middleware.

WebError provides a production version of the debugging middleware that can be used instead of WebError#evalerror. This is important because with evalerror users would be able to execute arbitrary python code on your system whenever an exception occurred.

This configuration uses PasteDeploy's PrefixMiddleware to automatically convert the X-Forwarded-Proto into the correct HTTP scheme in the WSGI environment. This is important so that the URLs generated by the application can distinguish between different domains, HTTP vs. HTTPS, and with some extra configuration to the paste_prefix filter it can even handle hosting the application under a different URL than /.

Running the paster processes:

paster serve --daemon --pid-file=paster_5000.pid production.ini http_port=5000
paster serve --daemon --pid-file=paster_5001.pid production.ini http_port=5001

Step 3: Serving Static Files with Nginx (Optional)

Assuming your static files are in a subdirectory of your pyramid application, they can be easily served using nginx's highly optimized web server. This will greatly improve performance because requests for this content will not need to be proxied to your WSGI application and can be served directly.

Warning

This is only a good idea if your static content is intended to be public. It will not respect any view permissions you've placed on this directory.

It's somewhat odd that the root doesn't point to the static directory, but it works because Nginx will append the actual URL to the specified path.

Step 4: Managing Your Paster Processes with Supervisord (Optional)

Turning on all of your paster processes manually and daemonizing them works for the simplest setups, but for a really robust server, you're going to want to automate the startup and shutdown of those processes, as well as have some way of managing failures.

Enter supervisord:

pip install supervisord

This is a great program that will manage arbitrary processes, restarting them when they fail, providing hooks for sending emails, etc when things change, and even exposing and XML-RPC interface for determining the status of your system.

Below is an example configuration that starts up two instances of the paster process, automatically filling in the http_port based on the process_num, thus 5000 and 5001.

This is just a stripped down version of supervisord.conf, read the docs for a full breakdown of all of the great options provided.

Something went wrong with that request. Please try again.