fork 0k-charms
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Boris Gallet d47482a1f3 chg: [rallly] update from v3.3.0 to v3.7.0 2 months ago
apache new: [apache,cyclos,mongo,piwigo] replace ``service_base_docker_image`` with ``service_ensure_image_ready`` for compatibility with compose ``1.7.1`` 3 months ago
bind new: [bind] add charm 2 years ago
bitwarden new: [bitwarden] upgrade to ``vaultwarden`` ``1.27.0`` 1 year ago
collabora new: [collabora] update version to ``2305.9.4`` 2 months ago
cron fix: [cron] prevent error to be stored in cache 1 month ago
cyclos new: [apache,cyclos,mongo,piwigo] replace ``service_base_docker_image`` with ``service_ensure_image_ready`` for compatibility with compose ``1.7.1`` 3 months ago
cyclos-ui new: [cyclos-ui] new charm 4 years ago
docker-host new: [docker-host] add ``ntfy`` installation and connection 4 weeks ago
docker-registry new: dev: [apache] store a ``url`` argument instead of a ``protocol`` argument. 5 years ago
docker-registry-auth new: [docker-registry-auth] allow usage of acl rules for public access. 4 years ago
docuseal new: [docuseal] new charm 6 months ago
drone new: [drone] add ``backup`` relation 3 years ago
drone-agent new: [drone-agent] implemented labels 5 years ago
etherpad new: [etherpad] add ``list`` and ``drop`` actions to list pads and drop a given pad 11 months ago
gitea chg: [gitea] ensure ``disable-registration`` is ``true`` by default 5 months ago
gitlab new: [gitlab] new charm 5 years ago
gogocarto fix: [gogocarto] improve solidity of cron scripts facing the ``no-matching-entries`` bug 2 months ago
gogocartojs new: [gogocartojs] added charm 4 years ago
hedgedoc new: doc: [Hedgedoc] add README to manage users with cli tool 4 months ago
hugo new: [hugo] add ``hugo`` charm 1 year ago
itty-bitty new: [itty-bitty] new charm 2 years ago
keycloak chg: [keycloak] upgrade to version ``17.0.1`` 2 years ago
letsencrypt fix: [cron] make cron build again 3 months ago
lo-xcgd new: [py3o-{fusion,server},lo-xcgd] add charm 4 years ago
logrotate fix: [cron] make cron build again 3 months ago
mailhog new: [mailhog] new charm 2 years ago
mariadb fix: [cron] make cron build again 3 months ago
mattermost fix: [mongo,odoo-tecnativa,mattermost,peertube,synapse,rocketchat,redis] avoid using ``find``'s ``-exec`` option as it fails 4 years ago
minecraft new: [minecraft] add type of install and ``paper`` type 11 months ago
mongo new: [apache,cyclos,mongo,piwigo] replace ``service_base_docker_image`` with ``service_ensure_image_ready`` for compatibility with compose ``1.7.1`` 3 months ago
monujo fix: [monujo] support version ``1.0.0-rc.8`` and up. 1 year ago
mysql fix: dev: removed ``--force-yes`` everywhere as it is deprecated 3 years ago
nextcloud new: [nextcloud] remove default skeleton directory 4 weeks ago
ntfy new: [ntfy] add some minimal documentation on the ``ntfy`` command line and authentication options 5 months ago
odoo-tecnativa fix: [odoo-tecnativa] support restoring large database file 3 months ago
onlyoffice new: [onlyoffice] add a forced enabling of the ``onlyoffice`` app in ``nextcloud`` 2 years ago
peertube chg: [peertube] upgrade to ``v4.1.0`` 2 years ago
piwigo new: [apache,cyclos,mongo,piwigo] replace ``service_base_docker_image`` with ``service_ensure_image_ready`` for compatibility with compose ``1.7.1`` 3 months ago
postgres fix: [cron] make cron build again 3 months ago
postgres-alpine new: ``charm`` and ``service`` are now clear distinct concept 6 years ago
precise new: [host] update ``btrfs-tools`` compilation dependencies 5 months ago
py3o-fusion new: [py3o-{fusion,server},lo-xcgd] add charm 4 years ago
py3o-server new: [py3o-{fusion,server},lo-xcgd] add charm 4 years ago
radicale new: [radicale] add new charm. 2 years ago
rallly chg: [rallly] update from v3.3.0 to v3.7.0 4 weeks ago
rancher chg: [mattermost,odoo-tecnativa,rancher-agent,rancher,traefik] restart policy is now automatically set for non run-once services. 5 years ago
rancher-agent chg: [mattermost,odoo-tecnativa,rancher-agent,rancher,traefik] restart policy is now automatically set for non run-once services. 5 years ago
redis new: [apache,peertube,redis] added new backup relation 4 years ago
rocketchat new: doc: [rocketchat] add sentence to stress the limitation of the migration mecanism 4 months ago
rsync-backup fix: [cron] make cron build again 3 months ago
rsync-backup-target new: [rsync-backup-target] add ``ssh-key {enable|disable} IDENT`` admin command 4 weeks ago
searx new: [searx] add charm 3 years ago
sftp fix: [cron] make cron build again 3 months ago
smtp-stub new: [smtp-stub] new charm 5 months ago
softether new: [softether] new charm. 8 years ago
solid new: [solid] add charm 1 year ago
synapse new: doc: [synapse] add a ``README.rst`` that was written at the time of the charm 2 years ago
traefik chg: [mattermost,odoo-tecnativa,rancher-agent,rancher,traefik] restart policy is now automatically set for non run-once services. 5 years ago
vsftp new: [vsftp] new charm 5 years ago
whoami new: [traefik,whoami] new charms 6 years ago
.gitignore new: pkg: add ``*/doc/`` to ``.gitignore`` !minor 5 months ago new: doc: add notes on login and password policy of charms 4 months ago


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


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.


TODO Through compose for full deployment of sets of services

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


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.


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.


TODO Through 0k-charm for bare hosts installs

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



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.


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

login and password policy

A charm have to manage different set of password. The best would be that the charm:

  • don't require user to choose password (less configuration)

  • will promote reasonable security practice.

There are 2 types of password:

  • inter-service passwords (ie: database access password), these are never used by human operator, and will be required to be known by the charms to set things up. These should be generated randomly (although they could be set also via configuration if mentionned).

    • they can only be changed by specific backend technical manipulation.

  • user service's admin password (ie: admin user of odoo, nextcloud)

    • they can be changed through the service interface.

    • this service interface is available to the public and the general users.

    • charm doesn't need the password to set things up around the service.

Inter-service passwords

  • Login should be defaulted to name of the service when possible

  • Should be defaulted to random values if not provided in configuration.

  • Should not be advertised even in the command line interface.

  • Should be reset-able anytime.

Interactive admin user service's password

  • Login should be defaulted to 'admin'

  • Should be defaulted to random values, and not be configurable in configuration.

  • Should be advertised at the end of compose up along with URL of services as long as the default value chosen by compose is still working.

  • Should not be advertised once it was changed by user.