From 1d7d049da001a3732c808bd42347469718144e40 Mon Sep 17 00:00:00 2001 From: Valentin Lab Date: Sun, 1 Dec 2019 15:56:07 +0100 Subject: [PATCH] added doc Signed-off-by: Valentin Lab --- README.org | 240 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 README.org diff --git a/README.org b/README.org new file mode 100644 index 0000000..0d39613 --- /dev/null +++ b/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 "/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 "/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