docker/README.rst
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Thu, 09 Mar 2017 17:33:13 +0100
changeset 217 5a0cebef1a8e
parent 7 7cde41667f01
permissions -rw-r--r--
[schema] Implement security for top level types (ArchiveTransfer, ArchiveUnit, AuthorityRecord and ConceptScheme). For now, we only need to setup ConceptScheme compound security since it's not done yet by the skos cube, while it is in eac and seda cubes. We need to follow a change in the seda cube to get tests to green. Closes #16684441

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