Option 2: Install from Source¶
This section describes how to install CKAN from source. Whereas Option 1: Package Installation requires Ubuntu 10.04, this way of installing CKAN is more flexible to work with other distributions and operating systems. Please share your experiences on our wiki: http://wiki.ckan.org/Install
This is also the option to use if you are going to develop the CKAN source.
This option is more complex than Option 1: Package Installation.
There is a page of help for dealing with Common error messages.
For support during installation, please contact the ckan-dev mailing list.
Install the Source¶
Ensure the required packages are installed.
If you have access to apt-get, you can install these packages as follows:
sudo apt-get install mercurial python-dev postgresql libpq-dev sudo apt-get install libxml2-dev libxslt-dev python-virtualenv sudo apt-get install wget build-essential git-core subversion sudo apt-get install solr-jetty openjdk-6-jdk
Otherwise, you should install these packages from source.
Package Description mercurial Source control python Python v2.5-2.7 postgresql PostgreSQL database libpq PostgreSQL library libxml2 XML library development files libxslt XSLT library development files virtualenv Python virtual environments wget Command line tool for downloading from the web build-essential Tools for building source code (or up-to-date Xcode on Mac) git Git source control (for getting MarkupSafe src) subversion Subversion source control (for pyutilib) solr Search engine jetty HTTP server (used for Solr) openjdk-6-jdk OpenJDK Java library
Create a Python virtual environment.
In your home directory run the command below. It is currently important to call your virtual environment pyenv so that the automated deployment tools work correctly.
cd ~ virtualenv pyenv
If you don’t have a python-virtualenv package in your distribution you can get a virtualenv.py script from within the virtualenv source distribution and then run python virtualenv.py pyenv instead.
To help with automatically installing CKAN dependencies we use a tool called pip. Make sure you have activated your environment (see step 3) and then install it from an activated shell like this:
Activate your virtual environment.
To work with CKAN it is best to adjust your shell settings so that your shell uses the virtual environment you just created. You can do this like so:
When your shell is activated you will see the prompt change to something like this:
(pyenv)[[email protected] ~/]$
An activated shell looks in your virtual environment first when choosing which commands to run. If you enter python now it will actually run ~/pyenv/bin/python, not the default /usr/bin/python which is what you want for CKAN. You can install python packages install this new environment and they won’t affect the default /usr/bin/python. This is necessary so you can use particular versions of python packages, rather than the ones installed with default paython, and these installs do not affect other python software on your system that may not be compatible with these packages.
Install CKAN code and other required Python packages into the new environment.
Choose which version of CKAN to install. Released versions are listed at https://github.com/okfn/ckan - click on the list of tags. For example: ckan-1.5
pip install --ignore-installed -e git+https://github.com/okfn/[email protected]#egg=ckan
Alternatively, if you are to develop CKAN, then you will probably want to use the latest ‘bleeding edge’ code. If using this version, we suggest you check CKAN has passed the automatic tests. Here is how to install the latest code:
pip install --ignore-installed -e git+https://github.com/okfn/ckan.git#egg=ckan
CKAN has a set of dependencies it requires which you should install too. These are listed in three text files: requires/lucid_*.txt, followed by WebOb explicitly.
First we install two of the three lists of dependencies:
pip install --ignore-installed -r pyenv/src/ckan/requires/lucid_missing.txt -r pyenv/src/ckan/requires/lucid_conflict.txt pip install webob==1.0.8
The --ignore-installed option ensures pip installs software into this virtual environment even if it is already present on the system.
WebOb has to be installed explicitly afterwards because by installing pylons with –ignore-installed you end up with a newer (incompatible) version than the one that Pylons and CKAN need.
Now to install the remaining dependencies in requires/lucid_present.txt and you are using Ubuntu Lucid 10.04 you can install the system versions:
sudo apt-get install python-pybabel python-psycopg2 python-lxml sudo apt-get install python-sphinx python-pylons python-repoze.who sudo apt-get install python-repoze.who-plugins python-tempita python-zope.interface
Alternatively, if you are not using Ubuntu Lucid 10.04 you’ll need to install them like this:
pip install --ignore-installed -r pyenv/src/ckan/requires/lucid_present.txt
This will take a long time. Particularly the install of the lxml package.
At this point you will need to deactivate and then re-activate your virtual environment to ensure that all the scripts point to the correct locations:
deactivate . pyenv/bin/activate
Setup a PostgreSQL database.
List existing databases:sudo -u postgres psql -l
It is advisable to ensure that the encoding of databases is ‘UTF8’, or internationalisation may be a problem. Since changing the encoding of PostgreSQL may mean deleting existing databases, it is suggested that this is fixed before continuing with the CKAN install.
Next you’ll need to create a database user if one doesn’t already exist.
If you choose a database name, user or password which are different from the example values suggested below then you’ll need to change the sqlalchemy.url value accordingly in the CKAN configuration file you’ll create in the next step.
Here we create a user called ckanuser and will enter pass for the password when prompted:sudo -u postgres createuser -S -D -R -P ckanuser
Now create the database (owned by ckanuser), which we’ll call ckantest:sudo -u postgres createdb -O ckanuser ckantest
- Create a CKAN config file.
Make sure you are in an activated environment (see step 3) so that Python Paste and other modules are put on the python path (your command prompt will start with (pyenv) if you have) then change into the ckan directory which will have been created when you installed CKAN in step 4 and create the CKAN config file using Paste. These instructions call it development.ini since that is the required name for running the CKAN tests. But for a server deployment then you might want to call it say after the server hostname e.g. test.ckan.net.ini.cd pyenv/src/ckan paster make-config ckan development.ini
If you used a different database name or password when creating the database in step 5 you’ll need to now edit development.ini and change the sqlalchemy.url line, filling in the database name, user and password you used.sqlalchemy.url = postgresql://ckanuser:[email protected]/ckantest
If you’re using a remote host with password authentication rather than SSL authentication, use:sqlalchemy.url = postgresql://<user>:<password>@<remotehost>/ckan?sslmode=disable
Advanced users: If you have installed CKAN using the Fabric file capability (deprecated), your config file will be called something like pyenv/ckan.net.ini. This is fine but CKAN probably won’t be able to find your who.ini file. To fix this edit pyenv/ckan.net.ini, search for the line who.config_file = %(here)s/who.ini and change it to who.config_file = who.ini.
We are moving to a new deployment system where this incompatibility will be fixed.
- Create database tables.
Now that you have a configuration file that has the correct settings for your database, you’ll need to create the tables. Make sure you are still in an activated environment with (pyenv) at the front of the command prompt and then from the pyenv/src/ckan directory run this command.
If your config file is called development.ini:paster --plugin=ckan db init
or if your config file is something else, you need to specify it. e.g.:paster --plugin=ckan db init --config=test.ckan.net.ini
You should see Initialising DB: SUCCESS.
If the command prompts for a password it is likely you haven’t set up the database configuration correctly in step 6.
- Create the cache directory.
You need to create the Pylon’s cache directory specified by ‘cache_dir’ in the config file.
(from the pyenv/src/ckan directory):mkdir data
- Setup Solr.
- Run the CKAN webserver.
NB If you’ve started a new shell, you’ll have to activate the environment again first - see step 3.
(from the pyenv/src/ckan directory):paster serve development.ini
Point your web browser at: http://127.0.0.1:5000/
The CKAN homepage should load.
Finally, make sure that tests pass, as described in Basic Tests.
You can now proceed to Post-Installation Setup.