rewrite the PostgreSQL example using a Dockerfile, and add details to it

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au> (github: SvenDowideit)

docs/sources/examples/postgresql_service.Dockerfile

@@ -0,0 +1,53 @@
+#
+# example Dockerfile for http://docs.docker.io/en/latest/examples/postgresql_service/
+#
+
+FROM ubuntu
+MAINTAINER SvenDowideit@docker.com
+
+# Add the PostgreSQL PGP key to verify their Debian packages.
+# It should be the same key as https://www.postgresql.org/media/keys/ACCC4CF8.asc 
+RUN apt-key adv --keyserver keyserver.ubuntu.com --recv-keys B97B0AFCAA1A47F044F244A07FCC7D46ACCC4CF8
+
+# Add PostgreSQL's repository. It contains the most recent stable release
+#     of PostgreSQL, ``9.3``.
+RUN echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main" > /etc/apt/sources.list.d/pgdg.list
+
+# Update the Ubuntu and PostgreSQL repository indexes
+RUN apt-get update
+
+# Install ``python-software-properties``, ``software-properties-common`` and PostgreSQL 9.3
+#  There are some warnings (in red) that show up during the build. You can hide
+#  them by prefixing each apt-get statement with DEBIAN_FRONTEND=noninteractive
+RUN apt-get -y -q install python-software-properties software-properties-common
+RUN apt-get -y -q install postgresql-9.3 postgresql-client-9.3 postgresql-contrib-9.3
+
+# Note: The official Debian and Ubuntu images automatically ``apt-get clean``
+# after each ``apt-get`` 
+
+# Run the rest of the commands as the ``postgres`` user created by the ``postgres-9.3`` package when it was ``apt-get installed``
+USER postgres
+
+# Create a PostgreSQL role named ``docker`` with ``docker`` as the password and
+# then create a database `docker` owned by the ``docker`` role.
+# Note: here we use ``&&\`` to run commands one after the other - the ``\``
+#       allows the RUN command to span multiple lines.
+RUN    /etc/init.d/postgresql start &&\
+    psql --command "CREATE USER docker WITH SUPERUSER PASSWORD 'docker';" &&\
+    createdb -O docker docker
+
+# Adjust PostgreSQL configuration so that remote connections to the
+# database are possible. 
+RUN echo "host all  all    0.0.0.0/0  md5" >> /etc/postgresql/9.3/main/pg_hba.conf
+
+# And add ``listen_addresses`` to ``/etc/postgresql/9.3/main/postgresql.conf``
+RUN echo "listen_addresses='*'" >> /etc/postgresql/9.3/main/postgresql.conf
+
+# Expose the PostgreSQL port
+EXPOSE 5432
+
+# Add VOLUMEs to allow backup of config, logs and databases
+VOLUME	["/etc/postgresql", "/var/log/postgresql", "/var/lib/postgresql"]
+
+# Set the default command to run when starting the container
+CMD ["/usr/lib/postgresql/9.3/bin/postgres", "-D", "/var/lib/postgresql/9.3/main", "-c", "config_file=/etc/postgresql/9.3/main/postgresql.conf"]

docs/sources/examples/postgresql_service.rst

@@ -9,152 +9,109 @@ PostgreSQL Service
 
 .. include:: example_header.inc
 
-.. note::
-
-    A shorter version of `this blog post`_.
-
-.. _this blog post: http://zaiste.net/2013/08/docker_postgresql_how_to/
-
 Installing PostgreSQL on Docker
 -------------------------------
 
-Run an interactive shell in a Docker container.
+Assuming there is no Docker image that suits your needs in `the index`_, you 
+can create one yourself.
 
-.. code-block:: bash
+.. _the index: http://index.docker.io
 
-    sudo docker run -i -t ubuntu /bin/bash
+Start by creating a new Dockerfile:
-
-Update its dependencies.
-
-.. code-block:: bash
-
-    apt-get update
-
-Install ``python-software-properties``, ``software-properties-common``, ``wget`` and ``vim``.
-
-.. code-block:: bash
-
-    apt-get -y install python-software-properties software-properties-common wget vim
-
-Add PostgreSQL's repository. It contains the most recent stable release
-of PostgreSQL, ``9.3``.
-
-.. code-block:: bash
-
-    wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
-    echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main" > /etc/apt/sources.list.d/pgdg.list
-    apt-get update
-
-Finally, install PostgreSQL 9.3
-
-.. code-block:: bash
-
-    apt-get -y install postgresql-9.3 postgresql-client-9.3 postgresql-contrib-9.3
-
-Now, create a PostgreSQL superuser role that can create databases and
-other roles.  Following Vagrant's convention the role will be named
-``docker`` with ``docker`` password assigned to it.
-
-.. code-block:: bash
-
-    su postgres -c "createuser -P -d -r -s docker"
-
-Create a test database also named ``docker`` owned by previously created ``docker``
-role.
-
-.. code-block:: bash
-
-    su postgres -c "createdb -O docker docker"
-
-Adjust PostgreSQL configuration so that remote connections to the
-database are possible. Make sure that inside
-``/etc/postgresql/9.3/main/pg_hba.conf`` you have following line:
-
-.. code-block:: bash
-
-    host    all             all             0.0.0.0/0               md5
-
-Additionaly, inside ``/etc/postgresql/9.3/main/postgresql.conf``
-uncomment ``listen_addresses`` like so:
-
-.. code-block:: bash
-
-    listen_addresses='*'
 
 .. note::
 
     This PostgreSQL setup is for development only purposes. Refer
-    to PostgreSQL documentation how to fine-tune these settings so that it
+    to the PostgreSQL documentation to fine-tune these settings so that it
-    is secure enough.
+    is suitably secure.
 
-Exit.
+.. literalinclude:: postgresql_service.Dockerfile
+
+Build an image from the Dockerfile assign it a name.
 
 .. code-block:: bash
 
-    exit
+    $ sudo docker build -t eg_postgresql .
 
-Create an image from our container and assign it a name. The ``<container_id>``
+And run the PostgreSQL server container (in the foreground):
-is in the Bash prompt; you can also locate it using ``docker ps -a``.
 
 .. code-block:: bash
 
-    sudo docker commit <container_id> <your username>/postgresql
+    $ sudo docker run -rm -P -name pg_test eg_postgresql
 
-Finally, run the PostgreSQL server via ``docker``.
+There are  2 ways to connect to the PostgreSQL server. We can use 
+:ref:`working_with_links_names`, or we can access it from our host (or the network).
+
+.. note:: The ``-rm`` removes the container and its image when the container 
+          exists successfully.
+
+Using container linking
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Containers can be linked to another container's ports directly using 
+``-link remote_name:local_alias`` in the client's ``docker run``. This will
+set a number of environment variables that can then be used to connect:
 
 .. code-block:: bash
 
-    CONTAINER=$(sudo docker run -d -p 5432 \
+    $ sudo docker run -rm -t -i -link pg_test:pg eg_postgresql bash
-      -t <your username>/postgresql \
-      /bin/su postgres -c '/usr/lib/postgresql/9.3/bin/postgres \
-        -D /var/lib/postgresql/9.3/main \
-        -c config_file=/etc/postgresql/9.3/main/postgresql.conf')
 
-Connect the PostgreSQL server using ``psql`` (You will need the
+    postgres@7ef98b1b7243:/$ psql -h $PG_PORT_5432_TCP_ADDR -p $PG_PORT_5432_TCP_PORT -d docker -U docker --password
-postgresql client installed on the machine.  For ubuntu, use something
+
-like ``sudo apt-get install postgresql-client``).
+Connecting from your host system
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assuming you have the postgresql-client installed, you can use the host-mapped port
+to test as well. You need to use ``docker ps`` to find out what local host port the 
+container is mapped to first:
 
 .. code-block:: bash
 
-    CONTAINER_IP=$(sudo docker inspect -format='{{.NetworkSettings.IPAddress}}' $CONTAINER)
+    $ docker ps
-    psql -h $CONTAINER_IP -p 5432 -d docker -U docker -W
+    CONTAINER ID        IMAGE                  COMMAND                CREATED             STATUS              PORTS                                      NAMES
+    5e24362f27f6        eg_postgresql:latest   /usr/lib/postgresql/   About an hour ago   Up About an hour    0.0.0.0:49153->5432/tcp                    pg_test
+    $ psql -h localhost -p 49153 -d docker -U docker --password
 
-As before, create roles or databases if needed.
+Testing the database
+^^^^^^^^^^^^^^^^^^^^
+
+Once you have authenticated and have a ``docker =#`` prompt, you can
+create a table and populate it.
 
 .. code-block:: bash
 
     psql (9.3.1)
     Type "help" for help.
 
-    docker=# CREATE DATABASE foo OWNER=docker;
+    docker=# CREATE TABLE cities (
-    CREATE DATABASE
+    docker(#     name            varchar(80),
+    docker(#     location        point
+    docker(# );
+    CREATE TABLE
+    docker=# INSERT INTO cities VALUES ('San Francisco', '(-194.0, 53.0)');
+    INSERT 0 1
+    docker=# select * from cities;
+         name      | location  
+    ---------------+-----------
+     San Francisco | (-194,53)
+    (1 row)
 
-Additionally, publish your newly created image on the Docker Index.
+Using the container volumes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use the defined volumes to inspect the PostgreSQL log files and to backup your
+configuration and data:
 
 .. code-block:: bash
 
-    sudo docker login
+    docker run -rm --volumes-from pg_test -t -i busybox sh
-    Username: <your username>
-    [...]
 
-.. code-block:: bash
+    / # ls
+    bin      etc      lib      linuxrc  mnt      proc     run      sys      usr
+    dev      home     lib64    media    opt      root     sbin     tmp      var
+    / # ls /etc/postgresql/9.3/main/
+    environment      pg_hba.conf      postgresql.conf
+    pg_ctl.conf      pg_ident.conf    start.conf
+    /tmp # ls /var/log
+    ldconfig    postgresql
 
-    sudo docker push <your username>/postgresql
-
-PostgreSQL service auto-launch
-------------------------------
-
-Running our image seems complicated. We have to specify the whole command with
-``docker run``. Let's simplify it so the service starts automatically when the
-container starts.
-
-.. code-block:: bash
-
-    sudo docker commit -run='{"Cmd": \
-      ["/bin/su", "postgres", "-c", "/usr/lib/postgresql/9.3/bin/postgres -D \
-      /var/lib/postgresql/9.3/main -c \
-      config_file=/etc/postgresql/9.3/main/postgresql.conf"], "PortSpecs": ["5432"]}' \
-      <container_id> <your username>/postgresql
-
-From now on, just type ``docker run <your username>/postgresql`` and
-PostgreSQL should automatically start.