HowTo/NginxWithUwsgi

This document describes how to configure MoinMoin to run under an NGINX web server and a uWSGI application server. This configuration is extremely resource-efficient, which makes it suitable for systems with limited memory (such as many Virtual Private Servers). If your Apache/mod_wsgi setup keeps running out of memory, then you've come to the right page.

This page is based on the actual configuration of a single wiki (rather than a farm) running on a Debian VPS. Attempts have been made to keep the instructions as portable as possible.

This page does not cover installation or configuration of NGINX beyond the bare minimum needed to interface with MoinMoin.

Contents

Installing uWSGI
Configuring uWSGI
Running uWSGI
Configuring NGINX

Installing uWSGI

Do not attempt to use any uWSGI packages supplied by your operating system. They will most likely be old, deprecated versions, and the online instructions won't match the software. Instead, download uWSGI source code and compile it. If you will only be using uWSGI for MoinMoin, then you only need to build it to run Python applications.

As of this writing, there is no installation method for uWSGI (e.g. "make install" does not work). You may simply move the entire source directory somewhere permanent (e.g. /usr/local/uwsgi-2.0.3) and then make a symbolic link to the program:

ln -s ../uwsgi-2.0.3/uwsgi /usr/local/bin/uwsgi

Obviously, substitute the version number for whichever version of uWSGI you have.

Configuring uWSGI

Inside your main wiki directory (wherever your wikiconfig.py file resides), create a new file called uwsgi.ini:

[uwsgi]
socket = /var/run/moin.sock
chmod-socket = 660

chdir = /usr/share/moin/server
wsgi-file = moin.wsgi

master
workers = 3
max-requests = 200
harakiri = 30
die-on-term

You will need to adjust some of these lines for your system. In particular, the chdir = /usr/share/moin/server should point to your wiki directory. This tells uWSGI where everything is located.

You may also want to adjust the workers line (which tells uWSGI how many worker processes to spawn), max_requests (how many requests each one is allowed to process, before being replaced -- this is in case of memory leaks), and harakiri (how many seconds before a stuck worker process is forcibly killed). die-on-term is optional; you may omit it if you prefer the default behavior. See uWSGI Configuration Options for explanations.

This configuration does not use threading. Each worker can only handle a single wiki request at a time. The advantage of this is that it consumes much less memory than most of the alternatives do (less than half the memory used by a single 10-thread Apache/mod_wsgi process, and more importantly, the amount of memory used is consistent rather than prone to wild fluctuations). Adjust the settings based on the needs of your site.

Next, you will need a user account to run uWSGI and the wiki. This account should be the owner of all the wiki's files. If you have previously been running MoinMoin under Apache, you might be using www or www-data as the owner, depending on your operating system and how you configured Apache. You may continue doing it this way, if you don't feel a need to separate the web server user from the wiki user. Or, you may set up a new account like moin to be the wiki user.

For the rest of this document, we will assume you are using moin as the wiki user. Modify the steps appropriately if you are using a different account.

If you were previously running MoinMoin via WSGI (perhaps with Apache 2.x and mod_wsgi), then you should already have a moin.wsgi file in the wiki directory. If so, you shouldn't need to modify it. If you don't have a moin.wsgi file, then copy the default one from the MoinMoin source directory (e.g. moin-1.9.7/wiki/server/moin.wsgi) into your wiki directory.

Running uWSGI

Now that all the pieces of uWSGI are in place, you need to get it to run. There are many different ways to do this, depending on your operating system and your personal preferences for managing daemons.

One choice is to use daemontools. If you wish to do this, install it according to its instructions (note: Linux users will need to apply a small patch -- basically replace extern int errno; with #include <errno.h>). Then create two directories and two files:

mkdir -p /etc/moin/log
mkdir -p /var/log/moin ; chown moin /var/log/moin

You may place the log directory anywhere; /var/log/moin is just an example. Be sure the directory you create is owned by the wiki user, and matches the name in the second script we're about to create.

Now, create /etc/moin/run:

#!/bin/sh
cd /var/moin || exit
exec 2>&1 /usr/local/bin/setuidgid moin /usr/local/bin/uwsgi uwsgi.ini

And /etc/moin/log/run:

#!/bin/sh
exec /usr/local/bin/setuidgid moin \
        /usr/local/bin/multilog t s300000 /var/log/moin

Finally, make them both executable, and then create a symbolic link to start the uWSGI service:

chmod 755 /etc/moin/run /etc/moin/log/run
ln -s /etc/moin /service/moin

This should cause 4 uwsgi processes to run (the master and 3 workers), and should create a socket in /tmp. If something goes wrong, first look for errors in the log directory, and if there are none, try ps auxww | grep readproc and look for errors there.

If you don't want to use daemontools, there are many other equivalent packages that can start uWSGI. Just make sure it runs uWSGI as the correct user account, with the uwsgi.ini file as its argument. For an absolutely minimalist configuration, you may be able to add a line to your /etc/rc.local file, if your operating system has one:

# Note: untested!
echo 'su moin -c "cd /var/moin && /usr/local/bin/uwsgi uwsgi.ini" &' >> /etc/rc.local

Configuring NGINX

Now that we have the uWSGI application server running, with a uwsgi protocol Unix domain socket /tmp/moin.sock for input, the final step is to set up our web server to talk to it.

If NGINX is already installed and running, and you simply want to add your MoinMoin wiki as a virtual domain, then create a new server block in an appropriate configuration file:

server {
    listen 80;
    server_name wiki.your.domain;

    location / {
        uwsgi_pass unix:/tmp/moin.sock;
        include uwsgi_params;
    }

    location ~ ^/moin_static[0-9]+/(.*) {
        alias /var/moin/static/$1;
    }

    location /favicon.ico {
        alias /var/moin/favicon.ico;
    }
}

Different NGINX configurations will place this file in different locations. Some possible locations include /etc/nginx/conf.d/ and /etc/nginx/sites-available/. Name the file according to your site's standard practices for virtual domains.

The locations for the static content need to match where you've placed yours. If you're converting from Apache, check the Apache configuration file to see where you were getting MoinMoin's static files.

The uwsgi_params line refers to a standard Debian configuration file, /etc/nginx/uwsgi_params. If your NGINX installation doesn't already have it, you may try this one:

uwsgi_param     QUERY_STRING            $query_string;
uwsgi_param     REQUEST_METHOD          $request_method;
uwsgi_param     CONTENT_TYPE            $content_type;
uwsgi_param     CONTENT_LENGTH          $content_length;

uwsgi_param     REQUEST_URI             $request_uri;
uwsgi_param     PATH_INFO               $document_uri;
uwsgi_param     DOCUMENT_ROOT           $document_root;
uwsgi_param     SERVER_PROTOCOL         $server_protocol;
uwsgi_param     UWSGI_SCHEME            $scheme;

uwsgi_param     REMOTE_ADDR             $remote_addr;
uwsgi_param     REMOTE_PORT             $remote_port;
uwsgi_param     SERVER_PORT             $server_port;
uwsgi_param     SERVER_NAME             $server_name;

Once you've created your new server block, run nginx -s reload to start using it.

MoinMoin: HowTo/NginxWithUwsgi

Installing uWSGI

Configuring uWSGI

Running uWSGI

Configuring NGINX