0k-compose

• Installation
  • Requirement
  • Installation
    • Compose binary
      • Linux/MacOSX
      • Windows WSL
    • Test
    • Charms
      • Linux/MacOSX
      • Windows WSL
  • Usage
  • Configuration
• Feature
  • Good mannered command line layer
    • Keeping command-line intact

\hypersetup{ linkcolor=blue, pdfborder={0 0 0 0} }

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

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

cd /tmp &&
wget https://git.0k.io/0k-compose.git/plain/bin/compose -O compose &&
chmod +x compose &&
mv compose /usr/local/bin/

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”.

## 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"

Test

You should be able to run:

compose --version

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:

cd ~ &&
git clone https://git.0k.io/0k-charms.git .charm-store

If you want to install them for general usage and intend to run compose with root access:

cd /srv &&
git clone https://git.0k.io/0k-charms.git charm-store

Windows WSL

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

Usage

Create a basic compose.yml, for instance:

odoo:

And then run:

compose up

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