1. Installation guide

1.1. Before starting

Indico runs on WSGI. There are WSGI modules for all major web servers. We normally run mod_wsgi, using the Apache httpd server. Here is the recommended setup:

  • Python 2.7+
  • Apache httpd 2.2+
  • mod_wsgi 3.3+ (by installing libapache2-mod-wsgi)

You will need some system libraries:

  • python-devel (or python-dev depending on your OS)
  • libxslt-devel
  • libxml2-devel
  • libffi-devel
  • libz-devel
  • openldap-devel (if you wish to use LDAP authentication)

Since some of the python libraries used by Indico require compiled modules you need a compiler such as gcc.

You will also need to easy_install python-ldap if you want LDAP to work.

1.2. Installing it

First of all, make sure your setuptools is up-to-date. You may want to execute:

# pip install -U setuptools

You can then either install Indico’s latest release or retrieve it from Git.

1.2.2. From our Git repository

You can find the source code in our Github repository. Cloning it is as easy as:

$ git clone https://github.com/indico/indico/

You should now have an indico directory. cd into it:

$ cd indico

Since you are building from source, you will need to install our development dependencies:

$ pip install -r requirements.dev.txt

And then fetch any non-Python external modules.

$ fab setup_deps

Finally, you can install Indico:

# python setup.py install

Or, alternatively, if you are just trying to set up an Indico development environment:

# python setup.py develop_config

The setup script will fetch all the dependencies for you and install Indico in your Python library path.

1.3. Post-Install script

The next step is to run indico_initial_setup:

# indico_initial_setup
No previous installation of Indico was found.
Please specify a directory prefix:
[/opt/indico]:

and follow the instructions that the script will provide. By default, Indico will be installed under /opt/indico, but the setup script allows you to specify other paths.

By the end of the process, you should have obtained some information on how to start the database:

If you are running ZODB on this host:
 - Review etc/zodb.conf and etc/zdctl.conf to make sure everything is ok.
 - To start the database run: zdaemon -C etc/zdctl.conf start

As well as some information on the paths:

indico.conf:      /opt/indico/etc/indico.conf

BinDir:           /opt/indico/bin
DocumentationDir: /opt/indico/doc
ConfigurationDir: /opt/indico/etc
HtdocsDir:        /opt/indico/htdocs

1.4. Configuring the Web Server

Indico needs to run behind a WSGI-compliant web server. This guide describes two options:

  • Apache HTTPD
  • Nginx/uWSGI

1.4.2. Configuring uWSGI/nginx (option 2)

Indico might be installed as a uWSGI application, in order to run on Nginx (and possibly on Varnish as well). Create a uWSGI application configuration file for indico on /etc/uwsgi/apps-available/indico.ini:

[uwsgi]
pythonpath = /opt/indico
processes = 4
threads = 2
wsgi-file = /opt/indico/htdocs/indico.wsgi
post-buffering = 1
autoload = true
master = true
workers = 2
no-orphans = true
pidfile = /run/uwsgi/%(deb-confnamespace)/%(deb-confname)/pid
socket = /run/uwsgi/%(deb-confnamespace)/%(deb-confname)/socket
chmod-socket = 660
log-date = true
uid = www-data
gid = www-data

Then symlink this configuration file at /etc/uwsgi/apps-enabled/indico.ini:

# ln -s ../apps-available/indico.ini /etc/uwsgi/apps-enabled/indico.ini

The uWSGI daemon should be started after ZODB is running, and if you commit any changes to indico configuration, the daemon should also be restarted:

# service uwsgi start

This will create the uwsgi daemon socket at /run/uwsgi/app/indico/socket.

1.4.2.1. Nginx configuration

By default all you need to do on Nginx is to redirect all Indico requests to the uwsgi socket. However, static files should be delivered directly. Here’s a sample configuration that works for both HTTP and HTTPS:

## Here's the upstream socket
upstream indico {
    server unix:/run/uwsgi/app/indico/socket;
}

## Uncomment the following lines in case you want to enable HTTPS
#ssl_certificate        /etc/ssl/certs/ssl-cert-snakeoil.pem;
#ssl_certificate_key    /etc/ssl/private/ssl-cert-snakeoil.key;

## uWSGI cache params:
uwsgi_cache_key     $scheme$host$request_uri;
uwsgi_cache_valid   200 302  1h;
uwsgi_cache_valid   301      1d;
uwsgi_cache_valid   any      1m;
uwsgi_cache_min_uses  1;
uwsgi_cache_use_stale error  timeout invalid_header http_500;

server {
    listen 80;
    ## uncomment the following line to enable HTTPS access
    #listen 443 ssl;

    server_name _;
    root                   /opt/indico/htdocs;
    index                  index.py;

    ## try to get static files directly, if not, send request to Indico upstream
    location ~* ^.+.(jpg|jpeg|gif|css|png|js|ico|html|xml|txt|pdf|swf|woff|ttf|otf|svg|ico)$ {
        access_log        off;
        expires           max;
        try_files $uri @indico;
    }

    ## This is should be the same path as the BaseURL configuration at indico.conf
    location / {
        include         uwsgi_params;
        uwsgi_pass      indico;
    }

    location @indico {
        include         uwsgi_params;
        uwsgi_pass      indico;
    }
}

If the file /etc/nginx/uwsgi_params does not exist, create it with the following content:

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;

Please note that the uwsgi_param UWSGI_SCHEME is not available by default, and it’s required in case you configure a server with both HTTP and HTTPS.

After setup, restart nginx:

# service nginx restart

1.5. Indico config file

The next step should be inspecting indico.conf and configuring it to fit your server configuration. indico.conf replaces the old config.xml, so you will have to update it with the paramaters that you already have in your config.xml.

From v1.2 on, the URLs will be shorter, alike http://my.indico.srv/event/2413/ instead of the historical http://my.indico.srv/conferenceDisplay.py?confId=2413. If you want to stay compatible with the old way, i.e. redirect from the old URLs to new URLs, then you need to set RouteOldUrls = True in your (new) indico.conf file.

1.6. Post-install tasks

For background tasks you need to run the Celery scheduler daemon:

# indico celery worker -B

If you have changed your server host name for some reason you may need to delete /opt/indico/tmp/vars.js.tpl.tmp.

1.7. Migration

In order to upgrade Indico you can do the following:

# easy_install -U indico
# indico_initial_setup --existing-config=/opt/indico/etc/indico.conf  # replace with the path to your indico.conf
# python /opt/indico/bin/migration/migrate.py --prev-version=<previous-version>
# service httpd restart