added doc

Signed-off-by: Valentin Lab <valentin.lab@kalysto.org>

README.org

@@ -0,0 +1,240 @@
+# include-in-agenda
+#+PROPERTY: Effort_ALL 0 0:30 1:00 2:00 0.5d 1d 1.5d 2d 3d 4d 5d
+#+PROPERTY: Max_effort_ALL 0 0:30 1:00 2:00 0.5d 1d 1.5d 2d 3d 4d 5d
+#+PROPERTY: header-args:python :var filename=(buffer-file-name)
+#+PROPERTY: header-args:sh :var filename=(buffer-file-name)
+#+TODO: TODO WIP BLOCKED | DONE CANCELED
+#+LATEX_HEADER: \usepackage[margin=0.5in]{geometry}
+#+LaTeX_CLASS: article
+#+OPTIONS: H:8 ^:nil prop:("Effort" "Max_effort") tags:not-in-toc
+#+COLUMNS: %50ITEM %Effort(Min Effort) %Max_effort(Max Effort)
+
+#+begin_LaTeX
+  \hypersetup{
+    linkcolor=blue,
+    pdfborder={0 0 0 0}
+  }
+#+end_LaTeX
+
+#+TITLE: 0k-compose
+
+#+LATEX: \pagebreak
+
+0k-compose defines and run multi-container setups with Docker.
+It is a wrapper around =docker-compose= that aims at offering:
+
+- very simple (short) service description
+- completely orchestrate deployment of a solution
+- deployed solution is reproducible and identical
+
+#+LATEX: \pagebreak
+
+#+LATEX: \pagebreak
+
+* Installation
+
+** Requirement
+
+You'll need:
+
+  - =bash= >= 4.3
+  - =docker= >= 17.06
+
+Expect to use command line and edit some files with your favorite
+editor.
+
+On MacOSX, you'll need to install homebrew
+
+https://www.topbug.net/blog/2013/04/14/install-and-use-gnu-command-line-tools-in-mac-os-x/
+
+** Installation
+
+*** Compose binary
+
+You can download this bash script and set it executable:
+https://git.0k.io/0k-compose.git/plain/bin/compose
+
+**** Linux/MacOSX
+For instance, you could
+
+#+BEGIN_SRC shell
+cd /tmp &&
+wget https://git.0k.io/0k-compose.git/plain/bin/compose -O compose &&
+chmod +x compose &&
+mv compose /usr/local/bin/
+#+END_SRC
+
+**** Windows WSL
+
+We need the real compose to be out of the WSL root and in the
+Docker available path, so this should work:
+
+You'll need administrative permission, for that just right click on
+the installed Linux environment such as Ubuntu and select “Run as
+Administrator”.
+
+#+BEGIN_SRC shell
+
+## We make sure we have access to ``cmd.exe``
+CMD=$(type -p cmd.exe >/dev/null) || {
+    for p in {/mnt,}/c/WINDOWS/SYSTEM32; do
+        if [ -x "$p"/cmd.exe ]; then
+            CMD="$p"/cmd.exe
+        fi
+    done
+    if [ -z "$CMD" ]; then
+        echo "cmd.exe is not found in \$PATH." \
+            "And could not find it in standard directories." >&2
+        return 1
+    fi
+}
+
+win_env() { "$CMD" /c "<nul set /p=%${1}%" 2>/dev/null; }
+wsl_path_env() { wslpath "$(win_env "${1}")"; }
+
+
+## Actual installation code:
+
+PROGRAM_PATH="$(wsl_path_env ProgramFiles)"/Compose &&
+mkdir -p "$PROGRAM_PATH/bin" &&
+cd /tmp &&
+wget https://git.0k.io/0k-compose.git/plain/bin/compose -O compose &&
+chmod +x compose &&
+mv compose "$PROGRAM_PATH"/bin/compose &&
+mkdir -p ~/.local/bin &&
+ln -sf "$PROGRAM_PATH"/bin/compose ~/.local/bin/
+cd "$OLDPWD"
+#+END_SRC
+
+*** Test
+
+You should be able to run:
+
+#+BEGIN_SRC shell
+compose --version
+#+END_SRC
+
+*** Charms
+
+You should get some charms to mode forward. Charms are sort of
+packages that know how to setup services.
+
+**** Linux/MacOSX
+If you are installing this for you user account in Linux or MacOSX:
+
+#+BEGIN_SRC shell
+cd ~ &&
+git clone https://git.0k.io/0k-charms.git .charm-store
+#+END_SRC
+
+If you want to install them for general usage and intend
+to run =compose= with root access:
+
+#+BEGIN_SRC shell
+cd /srv &&
+git clone https://git.0k.io/0k-charms.git charm-store
+#+END_SRC
+
+**** Windows WSL
+
+#+BEGIN_SRC shell
+win_env() { cmd.exe /c "<nul set /p=%${1}%" 2>/dev/null; }
+wsl_path_env() { wslpath "$(win_env "${1}")"; }
+
+PROGRAM_PATH="$(wsl_path_env ProgramFiles)"/Compose &&
+cd "$PROGRAM_PATH" &&
+git clone https://git.0k.io/0k-charms.git charm-store
+#+END_SRC
+
+** Usage
+
+Create a basic =compose.yml=, for instance:
+
+#+BEGIN_SRC yaml
+odoo:
+
+#+END_SRC
+
+And then run:
+
+#+BEGIN_SRC sh
+compose up
+#+END_SRC
+
+
+** Configuration
+
+=compose= needs to store various things on your host:
+
+- the =datastore= is the data of all services that will be run by
+ =compose= . This datastore can be saved and restored or moved around
+  between hosts to revive the exact same services at the same point
+  in time. It contains any data the service will produce : it can be
+  work data, logs, parameters if the service allows for some configuration.
+
+  On linux servers, when you are installing this with =root=
+  permissions, it is traditionally stored in =/srv/datastore=. On
+  local user installs you could tuck it in ``~/.compose/datastore``.
+
+- a state information directory for =compose= to store various
+  internal running information: compose is not a daemon running in the
+  back so it is storing state information in this directory. It is
+  basically configuration values for services (for instance: user and
+  password access between services, internal URL so that services
+  can talk to each others... and any configuration that can be generated
+  automatically, like configurations files in the service's format...)
+
+- a cache directory for =compose=, which is just a place to store
+  intermediate values of computationaly expensive code. The content of
+  this directory can be entirely wiped out and is cleaned by compose
+  regularly to avoid growing too much.
+
+
+It'll need to get a read access also to:
+
+- a =charms-store=, a directory tree filled with charms. A charm is a directory conforming
+  to charm rules (most importantly, it should hold a file named =metadata.yml=). A charm
+  describe how to spawn a service. We have charms for =postgres=, =rocketchat=, =apache=, ...
+
+When launching =compose=, it takes also a =compose.yml= to manage
+services to deploy that can be specified with the =-f MYCOMPOSEFILE=
+optional argument, or will be found automatially in current directory
+or parents of it.
+
+
+
+
+
+
+* Feature
+
+compose run 
+
+- much smaller and functional ``compose.yml`` file
+  - all boiler-plate code is considered technical details
+    and are moved in ``charms``
+- common compose-level API for same intents
+  - launching a 'frontend', whether it is 'ngnix' or 'apache'
+    is just one word to change in ``compose.yml``.
+- explicitely describe the relations between services and
+  manage their dependencies.
+- be a good mannered command-line layer that don't remove any
+  feature from ``docker-compose``.
+- allow complex setups and behavior out of ``docker-compose`` reach
+  through:
+  - =init= hooks that are run on the host before launching
+  - relation hooks that triggers only when connecting 2 services
+- it enforce a clear separation of responsabilities
+
+** Good mannered command line layer
+
+We want =compose= to be used as a drop-in replacement where ``docker-compose``
+can be used. With the following exception:
+
+- its own service file is named =compose.yml=.
+- some =compose='s service are subordinates
+
+
+*** Keeping command-line intact
+
+compose run