diff --git a/README.md b/README.md index 9fd95ff..ec9e2e7 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,169 @@ # Alakazam Proof-of-concept meta-configuration app-connector abra wrapper. + +## Advantages + +The following problems should be solved with this approach: + +- have global configuration that apply on every configuration: + - avoid copy pasta errors from reusing the same configuration for multiple instances + - avoid forgetting important configurations +- reduce manual configuration overhead for connecting multiple apps + - exchange domains + - share secrets + - set specific env vars +- have a minimal configuration file for each instance + - it should only contain parameters that differ from the defaults and the global configuration +- set a global subdomain convention + - each app will always have the same subdomain +- set up an instance with multiple connected apps in one run +- Automatic updates of the env configurations + - avoid manual env configuration at all + +## Configuration + +### Concept + +This concept contains the following configuration files. +Each configuration can be templated with jinja2 and global variables. + +1. `defaults.yml` + - It contains configurations for each app that are applied on each instance + - i.E. smtp config, language... + - This configuration is for the operator to avoid copy pasta errors +2. `domains.yml` + - It contains a mapping for each app to a subdomain + - i.e. `nextcloud: cloud.example.com` + - This configuration is for the operator to keep the same naming convention +3. `config.yml` + - a minimalist configuration per instance + - contains at least: + - the domain (and the server, if they differ) + - the apps to be installed + - can optionally contain instance specific configurations for each app +4. `combine.yml` + - contains the configuration steps that are required to combine apps with each other + - the env variables that should be uncommented + - specific values for env variables + - secrets that should be shared with each other + - commands that should be executed + - This configuration should not be touched by the operator + - It should be either split into the recipes repositories and maintained by the recipe maintainer or it should be maintained by the alakazam maintainer + +### App Configuration `` + +`defaults.yml`, `config.yml` and `combine.yml` contain a similar structure to configure the individual apps. +For each app the following configuration steps can be used: + +- `uncomment` + - uncomment each matching line + - this is useful for env variables that are used multiple times like `COMPOSE_FILE` +- `env` + - set the value for env variables +- `execute` + - `abra.sh` commands that should be executed after deployment +- `secrets` + - insert a specific value into a secret + - if the secrets can not be generated, i.e. smtp passwords + +The `combine.yml` configuration additionally contains + +- `shared_secrets` + - `:` + - a mapping to define which secrets should be shared between two apps + +Each configuration file can have a `GLOBALS` section, that cat be used to template the configuration with global values. + +``` +GLOBALS: + smtp_user: noreply + smtp_domain: example.org +authentik: + env: + AUTHENTIK_EMAIL__USERNAME: "{{smtp_user}}@{{smtp_domain}}" +nextcloud: + env: + MAIL_FROM_ADDRESS: "{{smtp_user}}" +``` + +### Configuration Structure + +1. `defaults.yml` + - there is an entry for each `` that should have global configuration + - the `` is configured according to "App Configuration" above + +``` +: + +``` + +2. `domains.yml` + +``` +``: .example.com +``` + +3. `config.yml` + +``` +domain: +server: +apps: + : + +``` + +4. `combine.yml` + - For each `` there is a `` that is only applied if the `config.yml` also contains the ``, to combine these two apps. + +``` +: + : + +``` + + +## Process + +Creating a new instance + +1. The config.yml is created by the operator to define the domain and required apps +2. `./alakazam.py init-server` + - installs `traefik` and `backup-bot-two` +3. `./alakazam.py setup-apps` + 1. the env files for each app are created + 2. the `defaults.yml` configs/secrets are applied on the env files + 3. the `config.yml` configs/secrets are applied on the env files + 4. the `combine.yml` configs/secrets are applied on the env files + - the shared_secrets are generated + `.example.com` is replaced according to `domains.yml` in the `