Setup

0. Preparation

You will need:

• Python 2.6+ (2.7+ encouraged);
• Python development packages [python-dev or python-devel depending on your linux distro]
• Virtualenv;
• libxml2 and libxsl development packages;
• git [git-core in some distros]

1. Preparing your Python virtual environment

$ cd ~/code
$ virtualenv indico
New python executable in indico/bin/python
Installing setuptools............done.
Installing pip...............done.
$ cd indico
$ source bin/activate

You can leave the virtualenv anytime using the deactivate command.

Option 1: If you are CERN staff/user, …

... you should do the following:

1. Ask an administrator to create an account for you on indicodev.cern.ch
2. Make sure you have a CERN AFS account with space
3. Clone the git repo as follows:

For all examples in this document, let's pretend both your local username and indicodev account are jdoe

$ mkdir src
$ git clone ssh://jdoe@indicodev.cern.ch/afs/cern.ch/project/indico/repo/indico.git src
Cloning into cds-indico...

jdoe@indicodev.cern.ch's password: 
remote: Counting objects: 50711, done.
remote: Compressing objects: 100% (11823/11823), done.
remote: Total 50711 (delta 38022), reused 50711 (delta 38022)
Receiving objects: 100% (50711/50711), 113.54 MiB | 900 KiB/s, done.
Resolving deltas: 100% (38022/38022), done.
$ 

Note: If you want, you can access the AFS repository directly without ssh to indicodov:

Either set up AFS on your own PC and access it directly

$ git clone /afs/cern.ch/project/indico/repo/indico.git src

or use a node of the public linux cluster, alike

$ git clone ssh://jdoe@lxplus.cern.ch/afs/cern.ch/project/indico/repo/indico.git src

Option 2: If you are not CERN staff/user

1. You won't have access to the CERN AFS repository. You should clone the git repo using http as follows:

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

2. If wish to send us patches/contributions, please read this first: Dev/Collaboration

2. Preparing the Development Environment

$ cd src
$ pip install reportlab
$ python setup.py develop_config

Follow the instructions. By the end of the processt you should have Indico installed in your virtualenv. The config script should also provide you with some instructions on how to start the DB. That's what we'll do in the next section.

3. Launching Indico

1. To start the ZODB database, type:

$ sudo zdaemon -C etc/zdctl.conf start

2. Then, start a development web server:

$ indico_shell --web-server

3. Open your browser and go to ​http://localhost:8000/indico/ - Indico should be up and running!

Git

4. Working with Git

Before starting any development you should perform some basic steps with Git:

Setup your local Git

You can modify your .git/config file in order to setup your git environment. Here, you can see an example of config file.

Create a new local branch

You must create a new branch for each new project, bug fixing, improvement,etc. That branch must be created from a base one, for instance, if your contribution will be integrated in the main branch 'master', you must create the new one based on that one, like this:

git checkout -b new-feature-A origin/master

Working in your new branch

Every time you finish a sub-task related to your new-feature-A, you must commit it to your local repo.

If there are new files, do:

git add path/to/my/new/file.py

and now commit:

git commit -a

Write always a comment for every commit (see rules here)

Update your branch

If there are new contributions in your base branch (in our example, origin/master) you can get them like this:

git fetch origin

and now rebase your branch with the updates (make sure you are currently in your branch new-feature-A):

git rebase origin/master

NEVER rebase a branch that has already been published and integrated.

Once your new-feature-A is finished

You will need to do fetch and rebase, as explained in the previous point. And then you are ready to push:

git push your-public-repo new-feature-A

your-public-repo is a copy of your repo which is somewhere else and that the integrator can access to fetch and merge your new feature. In order to do that you must have these lines in your .git/config file:

[remote "your-public-repo"]
        url = myserver.com:/path/to/my/repo/indico-my-username.git
        fetch = +refs/heads/*:refs/remotes/your-public-repo/*

Once, it is published you can warn the integrators in order to merge your code.

5. Troubleshooting

Q: The first time I go to ​http://(your_host_name)/indico/index.py, I get a strange error involving a SyntaxError and a template.

A: Maybe someone messed up the template. Or maybe you did like me and downloaded the source code with !TortoiseCVS in Windows, and then copied it from Windows to Linux. Try doing a checkout again from Linux.

Q: When Indico tries to send an email, it doesn't work.

A: Try changing the SMTP server in MaKaCConfig.py to cernmx.cern.ch.

Q: What does MaKaC mean. I cannot sleep without knowing the answer'''

A: Once upon a time, an Indico elder told me that it was not a monkey's name. It actually meant 'Make a Conference'.

Q: I got an error similar to: cannot write to such and such file.

A: Try changing the permissions of the files so that Indico can write on them. If Indico is trying to create a file in a directory, Indico should have read, write and execution rights on that directory. Also create the directory if it doesn't exist already!

Q: I get a DisconnectedError when connecting to Indico for the first time.

A: This can happen in the following situation:

• You are using python2.5 and (possibly) ZODB 3.4, 3.6, 3.7.
• You don't have a data.fs file in the data directory, i.e., you are starting without a database file.

In this case, you have to create an empty database file with the following file (courtesy of Pedro):

import ZODB
from ZODB import FileStorage, DB
import transaction

storage = FileStorage.FileStorage("data.fs")
db = DB(storage)
connection = db.open()
dbroot = connection.root()

transaction.commit()

connection.close()
db.close()
storage.close()

Q: When I try going to ​http://localhost/indico I get an error stating /var/www/indico cannot be found.

A: This usually means the default site created by the apache installation is conflicting with the indico site(s) you have configured. To remedy this, simply disable the default site which can be seen in /etc/apache2/sites-enabled, it may be entitled default or 000-default, substitute as necessary:

sudo a2dissite default
sudo service apache2 restart

Q: I'm getting an error where the MaKaC package cannot be found, resulting in errors when trying to use any part of Indico.

A: As development of Indico continues and the roadmap is traversed, the internal structure is being reconfigured into a more logical model. As a consequence of this, it is required to make a symbolic link in the root directory of your indico codebase to the indico/MaKaC directory to satisfy the package names:

user@hostname:~/indico$ ln -s indico/MaKaC

Q: I'm running the latest version of Ubuntu but Apache cannot read any of the files in my Indico folder, permissions and ownership have all been set correctly, what's happening?

A: This may be due to the facility available in modern Linux distributions to enable home drive encryption. If this was enabled, the only way to allow Indico to run is to place it in an area outside of the encrypted directory - it is not a configuration issue with Indico itself.