new file mode 100644

@@ -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"]

@@ -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.

-

-.. code-block:: bash

-

-    sudo docker run -i -t ubuntu /bin/bash

-

-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

+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

-    apt-get -y install postgresql-9.3 postgresql-client-9.3 postgresql-contrib-9.3

+Start by creating a new Dockerfile:

-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.

+.. note::

-.. code-block:: bash

+    This PostgreSQL setup is for development only purposes. Refer

+    to the PostgreSQL documentation to fine-tune these settings so that it

+    is suitably secure.

-    su postgres -c "createuser -P -d -r -s docker"

+.. literalinclude:: postgresql_service.Dockerfile

-Create a test database also named ``docker`` owned by previously created ``docker``

-role.

+Build an image from the Dockerfile assign it a name.

 .. code-block:: bash

-    su postgres -c "createdb -O docker docker"

+    $ sudo docker build -t eg_postgresql .

-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:

+And run the PostgreSQL server container (in the foreground):

 .. 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:

+    $ sudo docker run -rm -P -name pg_test eg_postgresql

-.. code-block:: bash

+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).

-    listen_addresses='*'

+.. note:: The ``-rm`` removes the container and its image when the container 

+          exists successfully.

-.. note::

+Using container linking

+^^^^^^^^^^^^^^^^^^^^^^^

-    This PostgreSQL setup is for development only purposes. Refer

-    to PostgreSQL documentation how to fine-tune these settings so that it

-    is secure enough.

-

-Exit.

+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

-    exit

-

-Create an image from our container and assign it a name. The ``<container_id>``

-is in the Bash prompt; you can also locate it using ``docker ps -a``.

+    $ sudo docker run -rm -t -i -link pg_test:pg eg_postgresql bash

-.. code-block:: bash

+    postgres@7ef98b1b7243:/$ psql -h $PG_PORT_5432_TCP_ADDR -p $PG_PORT_5432_TCP_PORT -d docker -U docker --password

-    sudo docker commit <container_id> <your username>/postgresql

+Connecting from your host system

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-Finally, run the PostgreSQL server via ``docker``.

+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=$(sudo docker run -d -p 5432 \

-      -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

-postgresql client installed on the machine.  For ubuntu, use something

-like ``sudo apt-get install postgresql-client``).

+    $ docker ps

+    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

-.. code-block:: bash

+Testing the database

+^^^^^^^^^^^^^^^^^^^^

-    CONTAINER_IP=$(sudo docker inspect -format='{{.NetworkSettings.IPAddress}}' $CONTAINER)

-    psql -h $CONTAINER_IP -p 5432 -d docker -U docker -W

-

-As before, create roles or databases if needed.

+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;

-    CREATE DATABASE

-

-Additionally, publish your newly created image on the Docker Index.

+    docker=# CREATE TABLE cities (

+    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)

-.. code-block:: bash

+Using the container volumes

+^^^^^^^^^^^^^^^^^^^^^^^^^^^

-    sudo docker login

-    Username: <your username>

-    [...]

+You can use the defined volumes to inspect the PostgreSQL log files and to backup your

+configuration and data:

 .. code-block:: bash

-    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

+    docker run -rm --volumes-from pg_test -t -i busybox sh

-    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

+    / # 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

-From now on, just type ``docker run <your username>/postgresql`` and

-PostgreSQL should automatically start.