0k-charms/README.org

* 0k-charms

This package provides charms, which are special system recipes, that are
meant to be executable and mangled together to allow managing a wide set
of services.

Inspired by [[https://discourse.juju.is/t/introduction-to-juju-charms/1188][juju charms]], these are mostly bash scripts organized by
service and meant to automate all administration tasks, from
installation, to connection with other services, or any other task a
service would need.

Several tools are able to read the current state of this repository to
effectively deploy full production grade services on different type of
platform.

The only real fully functional implementation is =0k-compose=. It will
use these charms to drive, prepare, and build in =docker=, complete sets
of services.

Another old solution called =lxc-deploy= was used actively before to deploy
services on LXC tool set until 2016 using these charms.

Bare hosts can also replay some recipes to install services directly
on them via the =0k-charm= project using the =charm apply=
command. Note that actually, as most recipes are bash executable, it
is still a viable option to copy-paste parts of source-code of these
scripts. These last two options are still used very often to bootstrap
installs of =docker-hosts= for instance.


* Maturity

Charms in these repository are in a wide set of maturity, from simple note
taking of shell commands, not even executable, to full charm allowing to
deploy services and manage the full life cycle of the service.

The repository in a whole is thus NOT considered as mature at all, and will
require some thorough cleaning and decisions to furthermore structure to reach
a state where it'll make sense to go full public.

* Usage

** TODO Through =compose= for full deployment of sets of services

Requires =0k-compose= package that contains the =compose= command line tool.

TBD

** TODO Through =lxc-deploy= for full install and deployment of services

Requires =lxc-scripts= package that holds several tools for LXC
management, amongst them is =lxc-deploy=.

TBD

** TODO Through =docker-build-charm= for docker image creation

Requires =0k-docker= package that holds several tools for docker
management, amongst them is =docker-build-charm=.

=docker-build-charm= will use the =install= recipes in a charm to
basically mimic the =Dockerfile= purpose and create a docker image for
a specific service.

TBD

** TODO Through =0k-charm= for bare hosts installs

Requires =0k-charm= package to get the =charm= command line util.

TBD


* Installation

Most tools should check the =CHARM_STORE= bash environment variable
that should be the path to reach the root of this repository. If not
defined, most tools will look in =/srv/charm-store= by default.

* Specs

** charm type

Not all charm are designed to set up a continuously running, listening
service.

In a charm's ~metadata.yml~, the root-level key ~type~ can have one of
these values:

- ~daemon~ (default)

  By default, a charm is of type ~daemon~. It's probably the most
  expected way to run a service: it brings up a process that is
 *always running*. Examples include charms like ~apache~, ~mysql~,
 ~postgres~.

  These charms bring up processes that typically open ports to provide
  their functionality, perform background tasks like checking the time
  and scheduling commands (as the ~cron~ charm), and may use files to
  trigger or report on their activities.

  In the final ~docker-compose.yml~, a ~daemon~ type charm will
  ensure that an entry is created for the service they manage,
  resulting in a container that stays in memory. As such they require
  a docker image. They will ensure that these entries are managed with
 ~restart: unless-stopped~ policy.

  The processes managed by these charms will be setup via
 ~docker-compose up~ actions at the end, and they will run in the
  background.

  Once brought up, the processes from these charms will consume CPU and
  memory resources indefinitely, until you manually bring them down.

  It makes sense to bring them ~up~ or ~down~.

- ~command~

  This charm type is used to prepare *a process that run and exits
  after execution*. These are more what could be expected of a
  "command", and are typically invoked by an other service for
  specific events.

  Example includes ~logrotate~, ~rsync-backup~, and ~letsencrypt~,
  which are charms of type ~run-once~.

  These charms are meant to setup commands that are triggered by
  services at specific moments or as a result of specific event. It is
  through their ~relation~ hooks with other services that they will
  ensure to be called when intended to. They are run through the
 ~docker-compose run~ call.

  Like ~daemon~'s typed charm, these charm will ensure that an entry
  is correctly added in the final ~docker-compose.yml~ with all the
  necessary options so it is ready to be triggered. They require also
  a docker image.

  But unlike ~daemon~'s typed charms, these charm will ensure that
  the entry they managed in the final ~docker-compose.yml~ *DO NOT*
  have an automatic restart policy.

  They consume CPU and memory resources only when running and release
  resources once finished.

- ~stub~

  A ~stub~ charm is more of a placeholder that doesn't have anything
  to run at all ! They don't need any docker image. These entities are
  used to hold information in ~compose.yml~ and can often be used to
  represent a real service managed externally (out of =compose=, on
  another host or through a different management system, such as a
  local installation, LXC, VirtualBox, etc.).

  For example, ~smtp-stub~ charm can be used to build an entity that
  will stand for an external ~smtp~ service. Through relations, these
  stubs offer interfaces similar to actual services in the setting up
  stage. For instance, a ~smtp-stub~ acts as a ~smtp-server~ provider,
  and can satisfy ~services~ that would require a ~smtp-server~
  provider.

  They generally implement relation hooks and act as providers.

  No entry is created for them in the final ~docker-compose.yml~.

  They do not use any CPU or memory resources