0k-compose/README.org

# 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?h=dev" -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