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.