diff --git a/README.rst b/README.rst
index a855d048f5a..46c07cd7f5c 100644
--- a/README.rst
+++ b/README.rst
@@ -30,16 +30,45 @@ Pootle.  Teams can manage their files, permissions, projects, and translate
 on-line.  Files can be downloaded for offline translation.
 
 
-Installation
+Getting started
+---------------
+
+The easiest way to get started is by using the docker demo. You will need docker
+installed on your system, and to be running as a user with permissions to manage
+docker.
+
+As the docker compose configuration is stored in the pootle directory, you will
+need ``git`` installed and ``pip`` for some minimal python dependencies to get
+set up.
+
+
+Virtualenv
+----------
+
+You can optionally use a virtualenv to install the python requirements. This
+will make it easier to install and run as a user other than ``root``
+
+
+Demo install
 ------------
 
+First install the requirements
+
+::
+
+  git clone https://github.com/translate/pootle
+  cd pootle
+  pip install -r requirements/host.txt
+
+You can now run the demo, using the ``makey`` command runner
+
 ::
 
-  pip install --pre Pootle
+  makey demo
 
-Don't forget to read the `installation guide
-<http://docs.translatehouse.org/projects/pootle/en/latest/server/installation.html>`_
-for important details.
+This will take a few moments to pull the required docker images, and
+once up you should be able to browse to your pootle server on
+http://localhost:8000
 
 
 Copying
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
index 20e45e34e28..af71cdb9fea 100644
--- a/docs/contents.rst.inc
+++ b/docs/contents.rst.inc
@@ -4,6 +4,11 @@ All you need to know
 The following pages cover the documentation of Pootle from a wide variety of
 perspectives, server administrator's, and developer's view.
 
+.. toctree::
+   :maxdepth: 2
+
+   getting-started/index
+
 .. toctree::
    :maxdepth: 2
 
diff --git a/docs/developers/docker.rst b/docs/developers/docker.rst
new file mode 100644
index 00000000000..c928cab0dba
--- /dev/null
+++ b/docs/developers/docker.rst
@@ -0,0 +1,82 @@
+.. _docker:
+
+Docker
+======
+
+You can install a development and test environment using docker.
+
+
+.. _docker#assumptions:
+
+
+Assumptions
+-----------
+
+- You have docker installed and working on your system
+- The user you are using has permissions to use docker
+
+
+.. _docker#virtualenv:
+
+Create a virtualenv (optional)
+------------------------------
+
+Installing with virtualenv keeps your host environment clean, and separates
+your development environment from the host.
+
+For example:
+
+.. code-block:: console
+
+  $ mkvirtualenv pootle
+  $ cd ~/virtualenvs/pootle
+
+
+.. _docker#clone:
+
+Clone the pootle repository
+---------------------------
+
+You most likely want to clone *your* fork of the pootle repository, so you
+can easily create Pull Requests for your changes.
+
+.. code-block:: console
+
+  (pootle): git clone git@github.com:$USER/pootle
+  (pootle): cd pootle/
+
+
+.. _docker#requirements:
+
+Install host requirements
+-------------------------
+
+.. code-block:: console
+
+  (pootle): pip install -r requirements/host.txt
+
+
+.. _docker#install:
+
+Install the pootle database
+---------------------------
+
+The default installer will create a postgresql database with
+
+.. code-block:: console
+
+  (pootle): makey install-dev
+
+This will take some time as it loads the default projects
+
+
+.. _docker#server:
+
+Run the development server
+--------------------------
+
+Once Pootle is installed you can run the development server with
+
+.. code-block:: console
+
+  (pootle): makey runserver
diff --git a/docs/developers/index.rst b/docs/developers/index.rst
index d669a87dd90..809d7620772 100644
--- a/docs/developers/index.rst
+++ b/docs/developers/index.rst
@@ -24,3 +24,4 @@ other way, make sure to read through this part.
    deprecation
    releasing
    plugins
+   docker
diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst
new file mode 100644
index 00000000000..866830493b0
--- /dev/null
+++ b/docs/getting-started/index.rst
@@ -0,0 +1,23 @@
+.. _getting_started:
+
+Getting started
+===============
+
+.. _getting_started-docker:
+
+Setting up the docker environment
+---------------------------------
+
+
+.. _getting_started-demo:
+
+Running the demo
+----------------
+
+
+
+.. _getting_started-dev:
+
+
+Setting up a development environment
+------------------------------------