In a departure from what I often write about, I'm going to talk a little bit about something that is tangentially related to what I actually do for a living: running a web server. So I'm going to give a brief tutorial on setting up uWSGI (in Emperor mode) and Nginx so that you can run one or more Python Flask instances on a server.
Why? Well, I'm far from a pro at anything related to networking or web development, but I have been writing a few web tools lately just for fun. Initially, I had several different Flask/Werkzeug instances running in what was essentially a dev mode on different ports on my server, and I had each of these ports forwarded. But...
...this was ungainly, running multiple Werkzeug instances was inefficient, I didn't want to have to forward all of those ports, and damn it, I wanted to do things right. But, as this isn't my area of expertise, it took me a while to put all of these pieces together, because many of the examples that I was able to find were light on the details. I'm putting this here in the hope that someone else in my situation might find it useful.
Installation
So here are the relevant details. I'm running Ubuntu 12.04 (I know, I know, I should update) and I'm using Python 2.7.2, Flask 0.10, uWSGI 2.0.6, and Nginx 1.1.19. If you are missing any of these, you'll want to install them with your package manager of choice. For example:
$ sudo apt-get install python $ sudo apt-get install uwsgi $ sudo apt-get install nginx $ pip install flask
The goal here is to run multiple Flask servers on one machine without having to worry about port numbers and the like. We'll start with just one, and I'm sure that you can figure the rest out from there.
Flask
First you need a Flask application to run. How about this one? I wrote it a few months ago because I wanted to translate GET requests to POST requests.
Navigate to the directory you'd like to install it to (probably
/opt/ or /var/www/), then clone it. You'll want to verify that it runs locally on its own first.$ cd /opt $ git clone https://github.com/spurll/post.git $ post/run.py
In a web browser on the same server, navigate to
http://localhost:9999 and verify that the application is accessible. If you're running headless (as I am) you can always spawn the process to the background with post/run.py & and then curl localhost:9999 and verify that you don't get an error back. You can now kill the Python process.Flask is now set up!
uWSGI
First, test that uWSGI will run your application correctly on its own:
$ cd /opt/post $ uwsgi --socket 127.0.0.1:9999 --protocol=http -w run:app
In this case,
run is the name of the Python source file that contains our application (/opt/post/run.py) and app is the name of the Werkzeug/Flask application object contained in that file. Verify that the application is accessible again from http://localhost:9999 as above.If everything is working correctly, kill the uWSGI instance. It's now time to configure uWSGI's Emperor mode. This allows us to essentially have one master process that oversees all of our web applications, starting (and restarting) them when needed and logging as appropriate. You will probably have to install a few plugins, too, using your package manager of choice. For example:
$ sudo apt-get install uwsgi-plugin-python $ sudo apt-get install uwsgi-plugin-http
By default, your uWSGI master configuration file will probably be located at
/etc/init/uwsgi.conf. Edit it with your editor of choice (I'm a Vim guy, myself):$ sudo vim /etc/init/uwsgi.conf
It should look something like this:
description "uWSGI" start on runlevel [2345] stop on runlevel [06] respawn env UWSGI=/usr/bin/uwsgi env LOGTO=/var/log/uwsgi/emperor.log exec $UWSGI --master --emperor /etc/uwsgi/apps-enabled --die-on-term --uid www-data --gid www-data --logto $LOGTO
You can change the location of the Emperor's log file by changing the
LOGTO environment variable. You can also modify which user (--uid) and group (--gid) the Emperor will run as.Now it's time to configure the applications. Your application-specific configuration files (in this case, for the POST program that we installed to
/opt/post/) will probably be found at /etc/uwsgi/apps-available/. Create a new file there and call it post.ini. It should like something like this:[uwsgi] # Variables base = /opt/post app = run callable = app # Generic Configuration plugins = http,python pythonpath = %(base) socket = /opt/run/%n.sock module = %(app) logto = /var/log/uwsgi/%n.log
Here,
base is the base directory of our application (the directory that contains the module we want to run), app contains the name of the module to run (in this case run, for run.py), callable is the name of the Werkzeug/Flask callable application object (if you don't supply this, uWSGI will assume that it's called application), and socket defines the location of the socket you'd like Nginx to use when communicating with your uWSGI server. The %n references the name of our file (sans extension) to maintain consistency.You'll need to ensure that the location of your sockets (in this case,
/opt/run/) exists and that the appropriate user (in this case, www-data) has write permissions.This configuration assumes that you want to run your program using the modules installed on your system's Python. To run the application in a virtual environment, add a line defining
home:home = %(base)/virtualenv
Where
virtualenv is the directory containing the Python virtual environment you'd like to use. (In our case, that would be at /opt/post/virtualenv/, if we were using a virtual environment.)Once you're ready, create a symbolic link to place the
post.ini file you've created in the apps-enabled directory:$ sudo ln -s /etc/uwsgi/apps-available/post.ini /etc/uwsgi/apps-enabled/post.ini
You can start the uWSGI process (if you haven't already) like this:
$ sudo service uwsgi start
As soon as your Emperor process sees an application configuration file in
apps-enabled it will start up a uWSGI instance to serve requests for that application. If you'd like to set up additional Flask applications at this time, simply install them and create uWSGI configuration files for each (and don't forget to link them to apps-enabled!). If you're having trouble, take a look at the logs.The uWSGI Emperor is now set up!
Nginx
We're almost there!
The default configuration file for Nginx should be located at
/etc/nginx/sites-available/default. Feel free to edit this one, or create your own. By default, Nginx will point requests on port 80 (the default HTTP port) to /usr/share/nginx/www. If you'd like to point them somewhere else (such as /var/www/) you can change that here. Here's a brief Nginx configuration file that you can use to run connect your uWSGI server to the outside world:# server unix:///path/to/your/site.sock; # For a file socket.
# server 127.0.0.1:9999; # For a port.
upstream post {
server unix:///opt/run/post.sock;
}
server {
listen 80;
server_name your.server.url;
access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log;
root /var/www;
index index.html index.htm;
# GET to POST
location /post {
include uwsgi_params;
uwsgi_param SCRIPT_NAME /post;
uwsgi_modifier1 30;
uwsgi_pass post;
}
}
Replace
your.server.url with the URL for your server (you can use localhost for testing purposes). This configuration assumes that you'd like your application to be accessible at http://your.server.url/post. If you'd like it to take the place of the main page at http://your.server.url/, things are even simpler:...
# GET to POST
location / {
include uwsgi_params;
uwsgi_pass post;
}
}
Once you're done, create a soft link to
/etc/nginx/sites-enabled/ for each of the entries in /etc/nginx/sites-available/. Now you can start your Nginx service.$ sudo service nginx start
Every time you modify the Nginx configuration file, you'll have to restart the it.
Port Forwarding
If you're running this server from your home or office and you need external access, don't forgot to forward port 80 so that Nginx is accessible. Instructions for your router are probably available here.
Sources
I used several sites while putting this all together. If you're stuck, they may contain additional information that I neglected to include here. Here are the most helpful of the bunch:
Deploying Flask on uWSGI
Multiple Django and Flask Sites with Nginx and uWSGI Emperor
How to Setup Nginx
I also had some help from my friends and colleagues BCJ and Curtis when I was initially setting up Nginx. Thanks, gents!
No comments:
Post a Comment