Installing OSQA with Nginx, uWSGI and SQLite3 on Ubuntu Lucid (10.04) Minimal

OSQA is an open-source django-based implementation of the famous Stack Overflow Q&A community infrastructure. Its codebase was largely inherited from a Chinese project CNProg, which, for various unfortunate reasons, has closed its community site and virtually stopped development since earlier this year.

OSQA is currently only available as subversion checkout and although there are some installation tutorials posted on its website and elsewhere on the internet, one may not necessarily find all the needed information easily for his/her particular configurations.

This is basically a documentation about the process of installing OSQA on a low-spec or low-end VPS (Virtual Private Server), with 128 MB guaranteed and 128 MB burst memory. The OS is the newest LTS (Long Term Support) offering from Canonical, Ubuntu Lucid 10.04 Minimal. The selection of Nginx as web server and uWSGI as application server is based on their high performance and low memory footprint. SQLite3 is used as database engine also because of its low memory requirements and because high-traffic is not expected for the near future of the site being built.

This documentation is posted in the hope that it will make things easier for those attempting similar configurations. For more convenient use, a semi-automatic installation script is available for download at the end of this post, but it is probably better to go through the major steps of the installation process with some explanations.

1. Preparations

First things first, let’s make sure we have all the latest important updates installed:

apt-get update
apt-get upgrade -y

Then we install the required dependencies in addition to some useful utilities:

for i in busybox-static \
         syslog-ng \
         sqlite3 \
         subversion \
         python-setuptools \
         python-pip \
         python-software-properties \
         ; do
  apt-get install $i -yf
done

OSQA needs to be able to send emails for account validation and user subscription functions to work. It is possible to use an external mail server by making appropriate settings in the admin interface after installation, but we can also use postfix as local mail server to handle OSQA outbound mails.

apt-get install postfix -y

The benefit of doing this is that OSQA will be functional regardless of the status of external mail server. When prompted, select ‘Internet Site’ and set mail name to the domain name of our site.

For security and performance reasons, if postfix is only used for outbound mails, we should make sure it only listens to local requests:

sed -i "s%^\(inet_interfaces\ =\ \).*%\1loopback-only%" /etc/postfix/main.cf

2. Installation of OSQA

OSQA depends on quite some python packages, which we satisfy by using pip:

for i in django \
         elementtree \
         south \
         markdown \
         html5lib \
         python-openid \
         sphinx \
         sphinxsearch \
         ; do
  pip install $i
done

Assuming we use /home as installation base folder and want to install OSQA to /home/osqa, the following commands will check out the latest svn version accordingly:

cd /home
rm -rf osqa
svn co http://svn.osqa.net/svnroot/osqa/trunk osqa

Next, go into the OSQA folder (/home/osqa in our example) and set up local settings by:

cd osqa
cp settings_local.py.dist settings_local.py

Use a text editor such as vi or nano and make appropriate changes to settings_local.py. You should at least make the following changes:

DATABASE_NAME = '/home/osqa/osqa_sqlite3.db'
DATABASE_ENGINE = 'sqlite3'
APP_URL = 'http://example.com' # Replace this with your domain name

In addition, you may also want to modify LANGUAGE_CODE, TIME_ZONE and DISABLED_MODULES.

Some admin functions of OSQA are only available in the django-style interface. For the style to display properly, related django files should be made available to the web server. We can set up a symlink in the OSQA folder:

ln -s /usr/local/lib/python2.6/dist-packages/django/contrib/admin/media /home/osqa/admin_media

Then we create the WSGI file for uWSGI.

cp osqa.wsgi.dist osqa.wsgi

In osqa.wsgi, modify the sys.path.append lines as well as the os.environ[‘DJANGO_SETTINGS_MODULE’] line according to the instructions. For our installation, these should look like the following:

sys.path.append('/home')
sys.path.append('/home/osqa')
os.environ['DJANGO_SETTINGS_MODULE'] = 'osqa.settings'

After all the settings are configured, we can initialize the database:

python manage.py syncdb --all
python manage.py migrate forum --fake

You will be prompted to create a ‘superuser’ at this stage, to which you should say ‘no’, as this is an ignored setting. The real ‘superuser’ is the first registered account after OSQA is set up and running.

Finally, set the owner of /home/osqa to the web server user (www-data in Ubuntu) and make the upload folder, log folder and database file writable:

chown -R www-data /home/osqa
chmod -R g+w /home/osqa/forum/upfiles /home/osqa/log /home/osqa/osqa_sqlite3.db

3. Server Installation

Nginx is available from official Ubuntu repository, but the version is a bit old. uWSGI is still in the process of making into the official repository. Fortunately, one of uWSGI Ubuntu package’s maintainers, Stephen Crosby (stevecrozz), offered recent versions of both Nginx and uWSGI on his ppa, which makes our job much easier:

add-apt-repository ppa:stevecrozz/ppa
apt-get update
apt-get install uwsgi nginx -yf

Assuming uWSGI is only to be used for OSQA, we set up its configuration file /etc/uwsgi.xml to look like this:

www-data
www-data


127.0.0.1:9090
/home/osqa
/home/osqa/osqa.wsgi
1

20
128


 

To configure Nginx to serve OSQA content, we simply add a new file to /etc/nginx/sites-enabled folder. The filename does not matter, but the content should look like the following:

server {
  listen          80 default;
  # Replace this with your domain name
  server_name     example.com;

  location /m/ {
    alias /home/osqa/forum/skins/;
  }

  location /upfiles/ {
    alias /home/osqa/forum/upfiles/;
  }

  location /admin_media/ {
    alias /home/osqa/admin_media/;
  }

  location / {
    include uwsgi_params;
    uwsgi_pass 127.0.0.1:9090;
  }
}

After the modifications, we should restart the server processes:

service uwsgi restart
service nginx restart

And that’s all. Input the domain name of your site into your browser, assuming that you have already set up proper A record in your DNS entry, and you should be able to see the OSQA community site running. Register an account, which will be automatically accepted as the ‘superuser’, and make necessary modifications in the administration interface.

You may experience a ‘500’ error after creating the account. That is because the default email settings are not usable and OSQA’s attempt to send you a notification email has failed. In order to make use of the local postfix mail server, you should do the following changes in ‘Email settings’ panel: set ‘Email Server’ to ‘localhost’; set ‘Email port’ to ’25’ and check ‘Use TLS’.

Finally, here is the installation script mentioned earlier. This script does all the above steps automatically, but you should provide a few settings at first, such as installation folder and server domain.

OSQA installation script (See next post for an updated version of this script)

Download it to your environment, open it in a text editor and modify the settings at the beginning of the script according to your needs (explanations about the settings are included), save the modified script, ‘chmod +x’ it, run it, and you’re done.

P.S. Note on memory footprint

The installation script defaults to 2 Nginx worker processes and 4 uWSGI worker processes, which, on top of postfix, syslog and other minimal system processes, will take up about 120 MB.