Clic Server configuration

This repository contains the complete configuration of the Clic's server. It uses Ansible scripts for automated installation and deployment.

Playbooks

There are two playbooks, at the root of the repository:

• init.yaml: Initial set up of the server, must be run after each the machine has been reinstalled. It is responsible for installing the minimal dependencies (e.g. ansible, borgbackup, docker, etc.) as well as the required ansible-roles and automatic updates.

• deploy.yaml: (Re)deploy one or several services, and setups/updates the automatic backups. It relies on extra variables to get the services' secrets or some configuration data (like the Unix user, backup repository, etc.). Ideally, it should be run through ansible-pull:

  ansible-pull \
      -U git@github.com:clicepfl/infra.git \ # URL of the infra repo
      -e @/var/secrets.yaml \ # File containing all the secrets
      deploy.yaml \
      --extra-vars SERVICES=keycloak # Optional. Services to (re)deploy

  The /var/secrets.yaml file, based on secrets.yaml.example, contains the configuration options and secrets (like database/admin passwords). The playbook will check beforehand that all the variables are present.

  Additional (optional) variables can also be passed to the playbook through the --extra-vars flags (as shown above):

  • SERVICES: comma-separated list of service to (re)deploy. Useful for partial updates, e.g. when calling from the webhook.
  • WH_BUILD (defaults to true): when redeploying the webhook, whether it should be recompiled. If set to false, only the configuration is updated.
  • DIRECTUS_SYNC_ONLY (defaults to false): if true, Directus' stack is not redeployed and only the schema sync is ran.

Services

Each service has a dedicated Ansible role for deployment. It is called by the deploy.yaml playbook, and is given as parameter service the corresponding entry in the services dictionnary from the secrets file. For example, the foo service's dedicated role will be in /roles/foo and, given the config below, can access {{ service.bar }} and {{ service.baz }}.

services:
  foo:
    bar: changeme
    baz: ssh://myrepo

In addition to thes per-service secrets, the top-level object general can be accessed by all roles through {{ general.my_secret }}.

Important: when using files/templates from the respective directories, you need to append the role_path variable at the start of the path (e.g. "{{ role_path }}/files/docker-compose.yaml").

If a service's role needs to generate a permanent file, it needs to be stored in the directory {{ general.config_dir }}/{{ SERVICES }} (general.config_dir is specified in the secrets.yaml file). If the service runs in a docker container, the file must be mounted into the container using a bind mount. Also note that bind mounts do not allow to change the permissions/ownership of the file, so the role must take care of setting those properly.

Caddy

Caddy is the reverse-proxy used to dispatch incoming HTTP requests to the different services. It also handles HTTPS with the client. It communicates with the services through HTTP, to avoid having to manage local certificates. Since it needs to handle connections on both IPv4 and IPv6, it needs to run on bare-metal, as docker swarm does not yet allow to bind to an IPv6 address.

Webhook

The webhook service is used to trigger (partial) re-deployment of the infrastructure. Unlike the other services, the webhook runs on bare metal, to be able to do all necessary modifications of the server.

It is designed to receive packages from GitHub, in order to automatically re-deploy services when they are updated. See the official documentation and the dedicated README.