Installation guide (development)¶
Installing System Packages¶
Do not use the default NodeJS packages from your Linux distribution as they are usually outdated or come with an outdated npm version.
Since only few Linux distributions include Python 3.9 in their package managers, we recommend installing
pyenv and then install the latest Python 3.9 version using
pyenv install 3.9.1 (adapt this command in case a newer version is available).
You can run
pyenv doctor once you installed and enabled pyenv in order to see whether all dependencies are
met. There’s a good chance that you need to install some additional system packages beyond those listed below, and using
this tool will tell you what exactly you need.
yum install -y gcc redis libjpeg-turbo-devel libxslt-devel libxml2-devel \ libffi-devel pcre-devel libyaml-devel redhat-rpm-config \ postgresql postgresql-server postgresql-contrib libpq-devel systemctl start redis.service postgresql.service
apt install -y --install-recommends libxslt1-dev libxml2-dev libffi-dev libpcre3-dev \ libyaml-dev build-essential redis-server postgresql libpq-dev
Then on Debian:
apt install -y libjpeg62-turbo-dev
And on Ubuntu:
apt install -y libjpeg-turbo8-dev zlib1g-dev
Creating the directory structure¶
You will need a directory in your file system to store Indico as well as its data files (archives, etc…). Some
developers keep all their code inside a
code dir. We will assume
mkdir -p ~/dev/indico/data
We will need a virtualenv where to run Indico:
cd ~/dev/indico pyenv local 3.9.1 python -m venv env
After setting the version with pyenv, it’s a good idea to use
python -V to ensure you are really running that
particular Python version; depending on the shell you may need to restart your shell first. In case you installed
a newer version than 3.9.1 earlier, adapt the pyenv command accordingly.
First, let’s clone Indico’s code base. If you’re going to contribute back to the project, it’s probably best if you clone your own GitHub fork of the project and set it as the origin:
git clone email@example.com:<your-github-username>/indico.git src cd src git remote add upstream https://github.com/indico/indico.git cd ..
Otherwise, cloning the upstream repository as the origin should be enough:
git clone https://github.com/indico/indico.git src
If you’re going to be changing the standard Indico plugins and/or the documentation, you can also clone those:
mkdir plugins git clone https://github.com/indico/indico-plugins.git plugins/base git clone https://github.com/indico/indico-user-docs.git user-docs
Setting up Maildump (recommended)¶
Some actions in Indico trigger automatic e-mails. Those will normally have to be routed through an SMTP server. This can become a problem if you’re using production data and/or real e-mails, as users may end up being spammed unnecessarily. This is why we advise that you include a fake SMTP server in your development setup. Maildump does exactly this and runs on Python. It should be quite simple to set up:
python -m venv maildump ./maildump/bin/pip install -U pip setuptools wheel ./maildump/bin/pip install maildump ./maildump/bin/maildump -p /tmp/maildump.pid
You’ll then be able to access the message log at http://localhost:1080.
Creating the DB¶
sudo -u postgres createuser $USER --createdb sudo -u postgres createdb indico_template -O $USER sudo -u postgres psql indico_template -c "CREATE EXTENSION unaccent; CREATE EXTENSION pg_trgm;" createdb indico -T indico_template
Let’s get into the Indico virtualenv:
source ./env/bin/activate pip install -U pip setuptools wheel cd src pip install -e '.[dev]' npm ci
Then, follow the instructions given by the wizard:
indico setup wizard --dev
You can then initialize the DB:
indico db prepare
To build the locales, use:
indico i18n compile-catalog indico i18n compile-catalog-react
./bin/maintenance/build-assets.py indico --dev --watch
On the second one we’ll run the Indico Development server:
indico run -h <your-hostname> -q --enable-evalex
Double-check that your hostname matches that which has been set in the config file (by the wizard).
It is also worth mentioning that when working on a plugin, it is necessary to run another webpack watcher to build the plugin assets. That can be accomplished using the same command as above with an argument specifying which plugin you want to build the assets for:
./bin/maintenance/build-assets.py <plugin-name> --dev --watch
You can also build the assets for all the plugins:
./bin/maintenance/build-assets.py all-plugins --dev <plugins-directory>
Installing TeXLive (optional)¶
If you need PDF generation in certain parts of Indico to work (e.g. for contributions and the Book of Abstracts), you need LaTeX. To install it, follow the LaTeX install guide.
Using HTTPS through nginx (optional)¶
If you wish to open your development server to others, then we highly recommend that you properly set HTTPS. While you could do so directly at the development server, it’s normally easier to proxy it through nginx and have it serve static files as well.
You should obviously install nginx first:
sudo yum install nginx # centos/fedora sudo apt install nginx # debian/ubuntu brew install nginx # macOS
Here is an example of a
nginx.conf you can use. It assumes your username is
jdoe and the hostname is
This configuration also assumes you’ve already got a secret key and certificate stored in
acme.crt respectively. In most cases you will probably use a self-signed certificate. There are many guides on-line
on how to generate a self-signed certificate, so we will
not cover it here.
If you’re using SELinux, you will need to set the following configuration options:
sudo setsebool -P httpd_can_network_connect 1 sudo setsebool -P httpd_read_user_content 1
Uploading large files will probably fail unless you do:
sudo chown -R jdoe:nginx /var/lib/nginx/tmp/
The Indico dev server should be run with the
indico run -h 127.0.0.1 -p 8000 -q --enable-evalex --url https://acme.example.org --proxy
You can then start nginx and access