Browse Source
added doc
added doc
Signed-off-by: Valentin Lab <valentin.lab@kalysto.org>lokavaluto/dev/master
1 changed files with 240 additions and 0 deletions
-
240README.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 |
||||
Write
Preview
Loading…
Cancel
Save
Reference in new issue