Installing CKAN using a Docker image¶
Important
These instructions require Docker >=1.0. The released version of Docker is 1.0.1 as at this writing.
Note
Installing CKAN using a Docker image is currently under evaluation. There may be omissions or inaccuracies in this documentation. In particular, the current Docker image omits the configuration required to run the DataStore/DataPusher. Proceed with caution.
This section describes how to install CKAN using a Docker image. Docker is a tool that allows all kinds of software to be shipped and deployed in a standard format, much as cargo is shipped around the world in standardised shipping containers.
CKAN is built into a binary image, which you can then use as a blueprint to launch multiple containers which run CKAN and attendant services in an isolated environment. Providing a full introduction to Docker concepts is out of the scope of this document: you can learn more in the Docker documentation.
Prerequisites¶
In order to install CKAN using Docker, you will need to have installed Docker. Please follow the instructions for installing Docker from the Docker documentation.
Installing CKAN¶
In the simplest case, installing CKAN should be a matter of running three commands: to run PostgreSQL, Solr, and CKAN:
$ docker run -d --name db ckan/postgresql
$ docker run -d --name solr ckan/solr
$ docker run -d -p 80:80 --link db:db --link solr:solr ckan/ckan
This start a new CKAN container in the background, connected to default installations of PostgreSQL and Solr also running in containers.
Warning
The default PostgreSQL container is INAPPROPRIATE FOR PRODUCTION USE. The default database username and password is “ckan:ckan” and if you do not change this the contents of your database may well be exposed to the public.
Note
The first time you run these docker run commands, Docker will have to download the software images: this may be quite slow. Once you’ve downloaded the images, however, subsequent calls to docker run will be much faster. If you want, you can run echo postgresql solr ckan | xargs -n1 -IIMG docker pull ckan/IMG to pre-fetch the images.
If all goes well you should now have a CKAN instance running. You can use docker ps to verify that your container started. You should see something like the following:
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
cab6e63c77b1 ckan/ckan:latest /sbin/my_init 30 days ago Up 1 minutes 0.0.0.0:80->80/tcp jovial_perlman
fb47b3744d6d ckan/postgresql:latest /usr/local/bin/run 9 days ago Up 1 minutes 5432/tcp db,jovial_perlman/db
96e963812fc9 ckan/solr:latest java -jar start.jar 15 days ago Up 1 minutes 8983/tcp solr,jovial_perlman/solr
Using the CKAN container id (here it’s cab6e63c77b1), you can perform other actions on your container, such as viewing the logs:
$ docker logs cab6e63c77b1
or stopping the container:
$ docker stop cab6e63c77b1
If you wish to run CKAN on a different port or bind it to a specific IP address on the machine, please consult the output of docker help run to see valid values for the -p/--publish option.
You can also configure the CKAN container to connect to remote PostgreSQL and Solr services, without using Docker links, by setting the DATABASE_URL and SOLR_URL environment variables:
$ docker run -d -p 80:80 \
-e DATABASE_URL=postgresql://ckanuser:password@192.168.0.5/ckan \
-e SOLR_URL=http://192.168.0.6:8983/solr/ckan
Running maintenance commands¶
Note
This is currently more fiddly than we would like, and we will hopefully soon add a helper command to make this easier.
You can run maintenance commands in their own ephemeral container by specifying a custom command for the container. For example, to create a sysadmin user called joebloggs:
$ docker run -i -t --link db:db --link solr:solr \
ckan/ckan \
/sbin/my_init -- \
/bin/bash -c \
'$CKAN_HOME/bin/paster --plugin=ckan sysadmin -c $CKAN_CONFIG/ckan.ini add joebloggs'
Customizing the Docker image¶
You may well find you want to customize your CKAN installation, either by setting custom configuration options not exposed by the Docker image, or by installing additional CKAN extensions. A full guide to extending Docker images is out-of-scope of this installation documentation, but you can use the functionality provided by docker build to extend the ckan/ckan image: http://docs.docker.com/reference/builder/.
For example, if you wanted custom configuration and the CKAN Spatial extension, you could build an image from a Dockerfile like the following:
FROM ckan/ckan
# Install git
RUN DEBIAN_FRONTEND=noninteractive apt-get update
RUN DEBIAN_FRONTEND=noninteractive apt-get install -q -y git
# Install the CKAN Spatial extension
RUN $CKAN_HOME/bin/pip install -e git+https://github.com/ckan/ckanext-spatial.git@stable#egg=ckanext-spatial
# Add my custom configuration file
ADD mycustomconfig.ini $CKAN_CONFIG/ckan.ini
You would then reference your built image instead of ckan/ckan when calling the docker run commands listed above.