docker/README.rst
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Wed, 22 Feb 2017 21:37:38 +0100
changeset 132 aca5be11649a
parent 7 7cde41667f01
permissions -rw-r--r--
Fix some labels to have a consistent capitalization

How to use the Dockerfile
=========================

With this Dockerfile, you can build a Docker image and run an instance of the
``cubicweb-seda`` cube that you can use for testing or demonstration purpose.

Requirements
------------

Before proceeding, check that you have:

* a folder where you can store your instance's configuration, for example
  ``/srv/docker/seda_demo/etc``. This folder has to be writeable by the
  Docker containers,

* a folder where you can store your instance's data, for example
  ``/srv/docker/seda_demo/data``. This folder has to be writeable by the
  Docker containers,

* a PostgreSQL instance available, and information about how to connect to it
  (hostname, TCP port, username, password),

* the HTTP URL where your Docker containers will be accessible, for example
  ``http://localhost:8080``


Building the image
------------------

Just ``cd`` to the directory where this file lies and run docker build::

    # cd </path/to/the/docker/demo/dir>
    # docker build -t seda_demo .

You can check that the image is actually known to Docker with::

    # docker images


First run: cube creation
------------------------

To create a new instance of ``cubicweb-seda``, first run the image
interactively::

    # docker run --rm -t -i -v /srv/docker/seda_demo/etc:/root/venv/etc/cubicweb.d -v /srv/docker/seda_demo/data:/root/venv/var/lib/cubicweb/instances  seda_demo /bin/bash
    docker#

The ``-v`` argument create a volume mapping the *host* folder to the
*container* folder where the instance configuration will be written.

Everything needed to create and launch an instance is installed in a Python
virutalenv. To activate the virtualenv, use the following command::

    docker# . venv/bin/activate
    (venv) docker#

You can now create an instance::

    (venv) docker# export CW_CUBES_PATH=/root/cubes
    (venv) docker# cubicweb-ctl create seda seda_demo

Answer all the questions about database connection. Then choose a username and
a password for the administrator account. You can leave all other choices to
their default values. **But do not create the database right now.**. Before
that you must edit files ``sources`` and ``all-in-one.conf`` in folder
``/root/venv/etc/cubicweb.d``. In ``sources``, you should edit the
database hostname. For example::

    db-host = pgsrv.yourcompany.lan

In ``all-in-one.conf``, you should edit the ``base-url`` parameter::

    base-url=http://localhost:8080/

You can now run the next CubicWeb commands, either ``db-create`` if database
does not already exists, or ``db-init`` if a database has already been created
for you::

    (venv) docker# cubicweb-ctl db-create -a seda_demo

Now check that you can start your instance::

    (venv) docker# cubicweb-ctl pyramid -D -l info seda_demo

If your instance starts correctly, you are now done with the instance creation.
Just leave the docker container and it will vanish thanks to the ``--rm``
arguments passed with the ``run`` command.


Second run: cube creation
-------------------------

It's time to run a persistent container that will serve your purpose. Thanks to
the volumes used previously, your instance's configuration and data has
survived the first container death (you can check that the *host* folders
``/srv/docker/seda_demo/etc`` and ``/srv/docker/seda_demo/data`` has been
populated). To run the final container, use to following command::

    # docker run --name seda_demo --detach --restart=always -p 8080:8080 -v /srv/docker/seda_demo/etc:/root/venv/etc/cubicweb.d -v /srv/docker/seda_demo/data:/root/venv/var/lib/cubicweb/instances cubicweb-seda