From 2ed2ba4e8caa2d70d57d124a2f3509f400d8187e Mon Sep 17 00:00:00 2001
From: Sven Dowideit <SvenDowideit@home.org.au>
Date: Fri, 7 Feb 2014 09:37:10 +1000
Subject: [PATCH] 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)
---
.../examples/postgresql_service.Dockerfile | 53 ++++++
docs/sources/examples/postgresql_service.rst | 179 +++++++-----------
2 files changed, 121 insertions(+), 111 deletions(-)
create mode 100644 docs/sources/examples/postgresql_service.Dockerfile
diff --git a/docs/sources/examples/postgresql_service.Dockerfile b/docs/sources/examples/postgresql_service.Dockerfile
new file mode 100644
index 0000000000..af1423f258
--- /dev/null
+++ b/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"]
diff --git a/docs/sources/examples/postgresql_service.rst b/docs/sources/examples/postgresql_service.rst
index 1c427563e7..5a2323471b 100644
--- a/docs/sources/examples/postgresql_service.rst
+++ b/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
-
-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='*'
+Start by creating a new Dockerfile:
.. note::
This PostgreSQL setup is for development only purposes. Refer
- to PostgreSQL documentation how to fine-tune these settings so that it
- is secure enough.
+ to the PostgreSQL documentation to fine-tune these settings so that it
+ 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>``
-is in the Bash prompt; you can also locate it using ``docker ps -a``.
+And run the PostgreSQL server container (in the foreground):
.. 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 \
- -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')
+ $ sudo docker run -rm -t -i -link pg_test:pg eg_postgresql bash
-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``).
+ postgres@7ef98b1b7243:/$ psql -h $PG_PORT_5432_TCP_ADDR -p $PG_PORT_5432_TCP_PORT -d docker -U docker --password
+
+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)
- psql -h $CONTAINER_IP -p 5432 -d docker -U docker -W
+ $ 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
-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;
- CREATE DATABASE
+ 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)
-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
- Username: <your username>
- [...]
+ docker run -rm --volumes-from pg_test -t -i busybox sh
-.. 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.