Run-in-docker manual
====================

The main purpose of the ``run-in-docker`` script is to provide a
convenient way to create a local setup of RefStack inside a Docker
container. It should be helpful for new developers and also for testing
new features.

Requirements:
^^^^^^^^^^^^^

-  ``Docker >= 1.6`` (How to update on
   `Ubuntu <http://www.ubuntuupdates.org/ppa/docker>`__)

How to use:
^^^^^^^^^^^

Just run the ``run-in-docker`` script, but is important to first set
env[REFSTACK\_HOST] with the public host/IP for your local API. If you
want to test RefStack with OpenStackid you should point a valid local
alias here. For example:

``export REFSTACK_HOST=myrefstack.com``

By default 127.0.0.1 is used.

After it completes, check that the site is running on https://127.0.0.1.

The script will build a RefStack docker image with all dependencies, and
will run a container from this image. By default, RefStack will run
inside this container. You also can run ``run-in-docker bash`` to get
access into the container. If you stop the RefStack server by pressing
'Ctrl-C', the container is kept alive and will be re-used next time.

You can customize the RefStack API config by editing
``docker/templates/refstack.conf.tmpl``. It is a bash template, so you
can use ${SOME\_ENV\_VARIABLE} in it.

This script can make the reviewing process much easier because it
creates separate containers for each review. Containers get names in the
form refstack\_{REVIEW-TOPIC}. Database schema changes are automatically
handled, too, where the script creates a data container for each
database revision (refstack\_data\_{DATA-BASE-REVISON}) and reuses it
where possible. For example, if a new review uses an existing database
revision, that database container will be used.

Available script options:
^^^^^^^^^^^^^^^^^^^^^^^^^

-  ``-r`` Force delete the RefStack container and run it again. This
   will update the RefStack config from template noted above.
-  ``-i`` Run a container with isolated MySQL data. By default MySQL
   data is stored in a refstack\_data\_{DATA-BASE-REVISON} container. It
   reuses this container if such one exists. If you want to drop the DB
   data, just execute
   ``sudo docker rm refstack_data_{DATA-BASE-REVISON}``.
-  ``-b`` Force delete RefStack image and build it again. This rebuilds
   the Python and JS environment for RefStack.
-  ``-d`` Turn on debug information.
-  ``-h`` Print usage message.

Useful in-container commands/aliases:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  ``api-up`` - sync project and run the RefStack API
-  ``api-init-db`` - initialize the RefStack database
-  ``api-db-version`` - get current migration version of the RefStack
   database
-  ``api-sync`` - sync project files in the container with the project
   files on the host
-  ``activate`` - activate the python virtual env
-  ``mysql`` - open the MySQL console