"Seegrid will be due for a migration to confluence on the 1st of August. Any update on or after the 1st of August will NOT be migrated"

CKAN Setup Guide

Contents

Related pages


Overview

There are two ways to install CKAN namely from package or from source. Installing from package is the most straight forward way but it requires Ubuntu 12.04 64-bit server. In addition, installing CKAN from package will include other software components in which it depends on such as Solr and PostgreSQL on the same server. If that prerequisite doesn't suit your operating environment and needs, you'll need to install CKAN from source instead. See the official CKAN installation documentation for further details.

Disclaimer: This setup guide is prepared for Geological Surveys in Australia and it doesn't replace the official CKAN documentation. Should you encounter any issue not mentioning in this setup guide, it is advised that you refer to the official CKAN documentation for help.

Installing CKAN from Package

Install CKAN Package

a. Update Ubuntu's package index:

sudo apt-get update

b. Install CKAN dependencies:

sudo apt-get install -y nginx apache2 libapache2-mod-wsgi libpq5

c. Download and install CKAN package:

wget http://packaging.ckan.org/python-ckan_2.0_amd64.deb

sudo dpkg -i python-ckan_2.0_amd64.deb

Install PostgreSQL and Solr

Note: This section provides instructions on how to set up Single Solr instance i.e. there will be only one Solr endpoint that uses a single schema file. Solr can be set up to have multiple configurations and indexes on the same instance. If you already have an instance of Solr installed and would like CKAN to use that Solr instance, you'll need to follow the Multiple Solr cores setup guide on CKAN website.

a. Install PostgreSQL, Solr and OpenJDK:

sudo apt-get install -y postgresql solr-jetty openjdk-6-jdk

Solr Configuration

b. Edit the Jetty configuration file (/etc/default/jetty). Look for the following properties in the file and replace their default values as follows:

NO_START=0
JETTY_HOST=127.0.0.1
JETTY_PORT=8983
JAVA_HOME=/usr/lib/jvm/java-6-openjdk-amd64/

c. Replace Solr's default schema.xml file with CKAN one. We also want to backup Solr's default schema.xml file.

sudo mv /etc/solr/conf/schema.xml /etc/solr/conf/schema.xml.bak

sudo ln -s /usr/lib/ckan/default/src/ckan/ckan/config/solr/schema-2.0.xml /etc/solr/conf/schema.xml

d. Start/restart the Jetty server:

sudo service jetty restart

e. Check to ensure Solr is running in your browser (replace localhost with your server address):

http://localhost:8983/solr/

http://localhost:8983/solr/admin

f. By default, CKAN makes use of Solr running on port 8983. If you have your own instance of Solr running on a separate port and have followed thru the Multiple Solr cores setup guide as mentioned above, you need to edit solr_url property in /etc/ckan/default/production.ini file and replace 127.0.0.1 with remote server address where your Solr instance is running. (You can skip this step if you don't have your own Solr instance)

## Search Settings

solr_url = http://127.0.0.1:8983/solr

PostgreSQL configuration

g. Check that the encoding of databases is UTF8, otherwise internationalisation may be a problem. CKAN official Setup PostgreSQL database documentation suggested that this should be fixed before continuing with the database configuration.

sudo -u postgres psql -l

h. Create a new PostgreSQL database user call ckan_default and enter a password when prompted. Take note of this password as we need it later. For the purpose of this setup guide, we'll be using "ckan#pwd" as the password.

sudo -u postgres createuser -S -D -R -P ckan_default

i. Create a new PostgreSQL database, called ckan_default, owned by the database user we previously created:

sudo -u postgres createdb -O ckan_default ckan_default -E utf-8

j. Edit the sqlalchemy.url property in /etc/ckan/default/production.ini file and set the correct password, database and database user. We'll make use of the password we entered in step (g).

## Database Settings

sqlalchemy.url = postgresql://ckan_default:ckan#pwd@localhost/ckan_default

k. Initialise CKAN database by running this command:

sudo ckan db init

l. The default installation of CKAN created an Apache configuration file called ckan_default (/etc/apache2/sites-enabled). Replace ServerName and ServerAlias with your server name and alternative name accordingly. (optional)
ServerName default.ckanhosted.com
ServerAlias www.default.ckanhosted.com

m. Restart Apache Web Server:

sudo service apache2 restart

Checking Your CKAN Instance

CKAN installation is now done. You should now have your CKAN instance installed. You can check if you CKAN instance is running in your web browser. (replace localhost with your server address)

http://localhost

You should see the following CKAN front page (image is taken from CKAN documentation website) if you've successfully installed CKAN:

ckan-front-page.png

Tip: CKAN uses Nginx to proxy request over from port 80 to 8080. If the above site doesn't work, you can troubleshoot if CKAN is running by going directly to port 8080 if that port is not blocked by your organisation's firewall. If you could access CKAN from port 8080 but not from port 80, you need to troubleshoot why the Nginx reverse proxy (/etc/nginx/sites-available/ckan) is not working.

Getting Started with Your CKAN instance

Now that you have CKAN installed and checked. The next thing to do is to create a CKAN sysadmin user. You need this user to administer CKAN and also to perform tasks in CKAN that require admin user access. To do that, we have to use CKAN's command line interface called paster on the server where CKAN is installed. Before running the paster command to create your first sysadmin user, you need to ensure CKAN's Python Virtual Environment (virtualenv) is activated and you are in your CKAN's source directory.

Note: A virtualenv, in summary, is an isolated working copy of Python which allows you to work on a specific project without worrying of affecting other projects.

a. Log in to the server where CKAN is installed and type in the following commands:

. /usr/lib/ckan/default/bin/activate
cd /usr/lib/ckan/default/src/ckan 

b. Create a user called "admin" and make this user a CKAN sysadmin. If "admin" user account already exists the user will be promoted to a sysadmin. Otherwise, you'll be prompted to enter a password and the user account will be created. You need to remember the password as we'll be using it later to create a CSW harvest source. For the purpose of this setup guide, we'll be using "adm#ckan" as the user password.

paster sysadmin add admin -c /etc/ckan/default/production.ini

c. Check CKAN's users site to ensure "admin" user is created (replace localhost with your server address):

http://localhost/user

You should see the following CKAN user page if you've successfully created the sysadmin user:

ckan-user-page.png

You can do more with CKAN's paster commands but we won't be looking into further details in this setup guide. See the official CKAN's Getting Started documentation if you want to learn more about CKAN commands and other getting started with tasks such as creating test data, configuring your CKAN site, etc.

What's next?

At this stage, you should have CKAN installed and running with one sysadmin user.

CKAN comes with many extensions or plugins that go beyond its basic functionality. You may want to look into CKAN's DataStore Extension and also enabling File Uploads in CKAN.

What we would like to do next is to add geospatial and remote harvesting capabilities to CKAN and we will guide you through the setup of those two extensions in CKANSpatialExtensionsSetupGuide.

Installing CKAN from Source

You should consider install CKAN from source if (taken from CKAN official documentation webiste):
  • You want to install CKAN on a 32-bit computer, or
  • You want to install CKAN on a different version of Ubuntu, not 12.04, or
  • You want to install CKAN on another operating system (eg. RedHat, CentOS, OS X), or
  • You want to run multiple CKAN websites on the same server, or
  • You want to run CKAN, Solr and PostgreSQL on different servers, or
  • You want to install CKAN for development

We've also tried out installing CKAN from souce but we haven't got those consolidated installation steps properly documented yet. As such, we'll leave this section out for the time being and encourage you to give it a go and probably contribute those installation instructions back into this setup guide (email cgadmin@csiro.au for access to this wiki page if you haven't got a SEEGrid's user account).

References

http://stackoverflow.com/questions/17217713/running-ckan-behind-nginx

http://docs.python-guide.org/en/latest/dev/virtualenvs/

https://pypi.python.org/pypi/virtualenv

 
Topic attachments
I Attachment Action Size Date Who Comment
ckan-front-page.pngpng ckan-front-page.png manage 96.6 K 29 Aug 2013 - 08:38 RichardGoh CKAN front page image - taken from CKAN documentation website.
ckan-user-page.pngpng ckan-user-page.png manage 109.6 K 29 Aug 2013 - 08:55 RichardGoh CKAN user page image
Topic revision: r9 - 10 Feb 2014, RichardGoh
 

Current license: All material on this collaboration platform is licensed under a Creative Commons Attribution 3.0 Australia Licence (CC BY 3.0).