Skip to content

Deploy Premix Docker Swarm stacks with Ansible

This section is under construction 🔨

This section is a serious work-in-progress, and reflects the current development on the sponsors's "premix" repository So... There may be errors and inaccuracies. Jump into Discord in the #dev channel if you're encountering issues 😁

Design

The ansible playbooks / roles in premix are intended to automate the deployment of an entire stack, along with selected recipes. The following design decisions influenced how the playbook is written:

  1. Users should be able to pull down updates to the repo without encountering conflicts in config files etc which they've changed.
  2. Secrets should be stored securely
  3. Configuration should be centralized (i.e., one place to manage changes)
  4. Duplication should be avoided
  5. The user is running in a self-managed, isolated environment, and secret storage is non-critical

Details

Duplication should be avoided

This means that ansible will use the same source files which we use to deploy swarm stacks manually (i.e., /kanboard/). This has some implications:

  1. Whenever a recipe requires more than just a .yml file, we provide "sample" files. The intention of sample files is to give the user direction on what to customize in order to deploy the stack. The sample files are named for their "real" counterparts, with -sample suffixed. For example, the sample file for traefikv1/traefik.toml is traefikv1/traefik.toml-sample. During ansible deployment, if the "real" version of the file doesn't exist, it'll be created from a copy of the sample file. However, if the user has already created teh "real" file, it'll remain untouched.

Why do we do this?

In an ansible-based deployment, we don't clone the premix repo to /var/data/config. Instead, we clone it somewhere local, and then use the playbook to launch the stack, including the creation of ceph shared storage at /var/data/config. The necessary files are then copied from the cloned repo into /var/data/config, so that they can be altered by the user, backed up, etc. This separation of code from config makes it easier for users to pull down updates to the premix repo, without having to worry about merge conflicts etc for the files they've manually changed during deployment.

Configuration should be centralized

What we don't want, is to manually be editing <recipe>/<recipe>.env files all over, and tracking changes to all of these. To this end, there's a config dictionary defined, which includes a subsection for each recipe. Here's an example:

config:
  traefik:
    dns_provider: route53
    env:
      # if you're using cloudflare
      # cloudflare_email: 
      # cloudflare_api_key:

      # if you're using route53
      AWS_ACCESS_KEY_ID: {{ vault_config.traefik.aws_access_key_id }}
      AWS_SECRET_ACCESS_KEY: {{ vault_config.traefik.aws_secret_access_key }}
      AWS_REGION: ""