Deploying a Source Install¶
Once you’ve installed CKAN from source by following the instructions in Installing CKAN from Source, you can follow these instructions to deploy your CKAN site using a production web server (Apache), so that it’s available to the Internet.
Note
If you installed CKAN from package you don’t need to follow this section, your site is already deployed using Apache and modwsgi as described below.
Because CKAN uses WSGI, a standard interface between web servers and Python web applications, CKAN can be used with a number of different web server and deployment configurations including:
- Apache with the modwsgi Apache module
- Apache with paster and reverse proxy
- Nginx with paster and reverse proxy
- Nginx with uwsgi
This guide explains how to deploy CKAN using Apache and modwsgi on an Ubuntu server. These instructions have been tested on Ubuntu 12.04.
If run into any problems following these instructions, see Troubleshooting below.
1. Create a production.ini
File¶
Create your site’s production.ini
file, by copying the development.ini
file you created in Installing CKAN from Source earlier:
cp /etc/ckan/default/development.ini /etc/ckan/default/production.ini
2. Install Apache and modwsgi¶
Install Apache (a web server) and modwsgi (an Apache module that adds WSGI support to Apache):
sudo apt-get install apache2 libapache2-mod-wsgi
3. Install an Email Server¶
If one isn’t installed already, install an email server to enable CKAN’s email features (such as sending traceback emails to sysadmins when crashes occur, or sending new activity email notifications to users). For example, to install the Postfix email server, do:
sudo apt-get install postfix
When asked to choose a Postfix configuration, choose Internet Site and press return.
4. Create the WSGI Script File¶
Create your site’s WSGI script file /etc/ckan/default/apache.wsgi with the following contents:
import os activate_this = os.path.join('/usr/lib/ckan/default/bin/activate_this.py') execfile(activate_this, dict(__file__=activate_this)) from paste.deploy import loadapp config_filepath = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'production.ini') from paste.script.util.logging_config import fileConfig fileConfig(config_filepath) application = loadapp('config:%s' % config_filepath)
The modwsgi Apache module will redirect requests to your web server to this WSGI script file. The script file then handles those requests by directing them on to your CKAN instance (after first configuring the Python environment for CKAN to run in).
5. Create the Apache Config File¶
Create your site’s Apache config file at /etc/apache2/sites-available/ckan_default, with the following contents:
<VirtualHost 0.0.0.0:80> ServerName default.ckanhosted.com ServerAlias www.default.ckanhosted.com WSGIScriptAlias / /etc/ckan/default/apache.wsgi # Pass authorization info on (needed for rest api). WSGIPassAuthorization On # Deploy as a daemon (avoids conflicts between CKAN instances). WSGIDaemonProcess ckan_default display-name=ckan_default processes=2 threads=15 WSGIProcessGroup ckan_default ErrorLog /var/log/apache2/ckan_default.error.log CustomLog /var/log/apache2/ckan_default.custom.log combined </VirtualHost>
Replace default.ckanhosted.com
and www.default.ckanhosted.com
with the
domain name for your site.
This tells the Apache modwsgi module to redirect any requests to the web server to the WSGI script that you created above. Your WSGI script in turn directs the requests to your CKAN instance.
6. Enable Your CKAN Site¶
Finally, enable your CKAN site in Apache:
sudo a2ensite ckan_default sudo service apache2 reload
You should now be able to visit your server in a web browser and see your new CKAN instance.
Troubleshooting¶
Default Apache Welcome Page¶
If you see a default Apache welcome page where your CKAN front page should be, it may be because the default Apache config file is overriding your CKAN config file (both use port 80), so disable it and restart Apache:
sudo a2dissite default sudo service apache2 reload
403 Forbidden and 500 Internal Server Error¶
If you see a 403 Forbidden or 500 Internal Server Error page where your CKAN
front page should be, you may have a problem with your unix file permissions.
The Apache web server needs to have permission to access your WSGI script file
and all of its parent directories. The permissions of the file should look
like -rw-r--r--
and the permissions of each of its parent directories
should look like drwxr-xr-x
.
IOError: sys.stdout access restricted by mod_wsgi¶
If you’re getting 500 Internal Server Error pages and you see IOError:
sys.stdout access restricted by mod_wsgi
in your log files, it means that
something in your WSGI application (e.g. your WSGI script file, your CKAN
instance, or one of your CKAN extensions) is trying to print to stdout, for
example by using standard Python print
statements. WSGI applications are
not allowed to write to stdout. Possible solutions include:
Remove the offending print statements. One option is to replace print statements with statements like
print >> sys.stderr, "..."
Redirect all print statements to stderr:
import sys sys.stdout = sys.stderr
Allow your application to print to stdout by putting
WSGIRestrictStdout Off
in your Apache config file (not recommended).
Also see https://code.google.com/p/modwsgi/wiki/ApplicationIssues
Log Files¶
In general, if it’s not working look in the log files in /var/log/apache2
for error messages. ckan_default.error.log
should be particularly
interesting.
modwsgi wiki¶
Some pages on the modwsgi wiki have some useful information for troubleshooting modwsgi problems:
- https://code.google.com/p/modwsgi/wiki/ApplicationIssues
- http://code.google.com/p/modwsgi/wiki/DebuggingTechniques
- http://code.google.com/p/modwsgi/wiki/QuickConfigurationGuide
- http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines
- http://code.google.com/p/modwsgi/wiki/FrequentlyAskedQuestions
- http://code.google.com/p/modwsgi/wiki/ConfigurationIssues