From bfe07785d04e15bea0bb5f30ea76b756b4155451 Mon Sep 17 00:00:00 2001
From: sslypushenko <sslypushenko@mirantis.com>
Date: Wed, 19 Aug 2015 14:48:00 +0300
Subject: [PATCH] Add documentation for run-in-docker script

Change-Id: I39d039ea54adcafb15dc35896aa911c0c0333ea0
---
 doc/refstack.md      |  4 ++++
 doc/run_in_docker.md | 56 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 doc/run_in_docker.md

diff --git a/doc/refstack.md b/doc/refstack.md
index cef6534a..5767f0ae 100755
--- a/doc/refstack.md
+++ b/doc/refstack.md
@@ -1,5 +1,9 @@
 Refstack Quickstart
 ===================
+
+You can use docker for [one-click setup](run_in_docker.md)
+or follow step-by-step instructions below.
+
 ####Install API dependencies (on ubuntu 14.x)..
 
 - `sudo apt-get install git python-dev libssl-dev python-setuptools`
diff --git a/doc/run_in_docker.md b/doc/run_in_docker.md
new file mode 100644
index 00000000..a44dc023
--- /dev/null
+++ b/doc/run_in_docker.md
@@ -0,0 +1,56 @@
+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 rebuids 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