diff --git a/doc/maintaining/installing/index.rst b/doc/maintaining/installing/index.rst index 487f10d6056..c9af553933e 100644 --- a/doc/maintaining/installing/index.rst +++ b/doc/maintaining/installing/index.rst @@ -3,7 +3,13 @@ Installing CKAN --------------- Before you can use CKAN on your own computer, you need to install it. There are -two ways to install CKAN, from package, or from source. +three ways to install CKAN: + +#. Install from an operating system package +#. Install from source +#. Install using a Docker_ image + +.. _Docker: http://www.docker.com/ From package is the quickest and easiest way to install CKAN, but it requires Ubuntu 12.04 64-bit. **You should install CKAN from package if**: @@ -26,6 +32,15 @@ See :doc:`install-from-package`. See :doc:`install-from-source`. +**You should install using Docker if**: + +* You want to deploy CKAN on any server that can run Docker, regardless of + operating system +* You want a deployment mechanism that remains the same as you move from vanilla + CKAN to a heavily customised deployment + +See :doc:`install-using-docker`. + If you've already setup a CKAN website and want to upgrade it to a newer version of CKAN, see :doc:`/maintaining/upgrading/index`. @@ -36,4 +51,5 @@ version of CKAN, see :doc:`/maintaining/upgrading/index`. install-from-package install-from-source + install-using-docker deployment diff --git a/doc/maintaining/installing/install-using-docker.rst b/doc/maintaining/installing/install-using-docker.rst new file mode 100644 index 00000000000..fc57187fec7 --- /dev/null +++ b/doc/maintaining/installing/install-using-docker.rst @@ -0,0 +1,141 @@ +==================================== +Installing CKAN using a Docker image +==================================== + +.. note:: + Installing CKAN using a Docker image is currently under evaluation. There may + be omissions or inaccuracies in this documentation. 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`_. + +.. _Docker: http://www.docker.com/ +.. _Docker documentation: http://docs.docker.com/ +.. _standardised shipping containers: https://en.wikipedia.org/wiki/Intermodal_container + + +------------- +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 `_. + +You will also need to have separately configured both the |postgres| database +and the |solr| search index. Details of this installation will differ between +operating systems. On Ubuntu, you can run:: + + sudo apt-get install -y postgresql solr-jetty + +after which you should follow the instructions in :ref:`postgres-setup` and +:ref:`setting up solr` to configure these services. + + +--------------- +Installing CKAN +--------------- + +In the simplest case, installing CKAN should be a matter of running a single +command. For example, to install the latest available version of the CKAN image +as published to the `Docker hub`_, and assuming you installed |postgres| and +|solr| as described in :ref:`postgres-setup` and :ref:`setting up solr`, you can +run:: + + $ docker run -d -p 5000:80 \ + -e DATABASE_URL=postgresql://ckan_default:@/ckan_default \ + -e SOLR_URL=http://:8983/solr/ckan_default \ + ckan/ckan + +.. _Docker hub: https://hub.docker.com/ + +where you must replace ```` with the password you chose for your +database user and ```` with the local IP address of your server. This +will start a new CKAN container in the background, listening on port 5000. + +.. note:: + The first time you run this ``docker run`` command, Docker will have to + download the ``ckan/ckan`` image: this may be quite slow, as the image + contains all of CKAN's dependencies pre-built. Once you've downloaded the + image, however, subsequent calls to ``docker run`` will be much faster. If + you want, you can ``docker pull ckan/ckan`` to pre-fetch the image. + +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:5000->80/tcp jovial_perlman + +Using the container id (here it's ``cab6e63c77b1``), you can perform other +actions on your container, such as viewing the logs:: + + $ docker logs cab6e63c77b1 + +listing the port bindings for the container:: + + $ docker ports 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. + + +---------------------------- +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 (configured +with the same ``DATABASE_URL`` and ``SOLR_URL``) by specifying a custom command +for the container. For example, to create a sysadmin user called ``joebloggs``:: + + $ docker run -i -t -e DATABASE_URL=... -e SOLR_URL=... \ + 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.