== Dotege

Dotege is a tool to automatically generate configuration files from templates
based on running docker containers. It also obtains SSL certificates for
domains using Let's Encrypt, and can send a signal (such as HUP) to another
container when the template changes.

Out of the box it supports writing a HAProxy configuration file with
appropriate entries for all containers with `com.chameth.*` labels.
This enables automatic reverse proxying to any container with the
relevant networks.

=== Configuration

Dotege is configured using environment variables:

`DOTEGE_CERT_DESTINATION`::
The folder where certificates will be placed. Defaults to `/data/certs`.

`DOTEGE_DNS_PROVIDER`::
The DNS provider to use. Must be one https://go-acme.github.io/lego/dns/[supported by Lego].
The DNS provider will also be configured using environmental variables, as documented by
the Lego project. Required.

`DOTEGE_ACME_CACHE_FILE`::
The path to a JSON file to store ACME credentials and certificates. This file will
contain the private keys for all certificates generated by Dotege, so must not
be accessible to other users or processes. Defaults to `/data/config/certs.json`.

`DOTEGE_ACME_EMAIL`::
The e-mail address to provide to the ACME service for updates, renewal reminders, etc.
Required.

`DOTEGE_ACME_ENDPOINT`::
The ACME server to request certificates from. Defaults to the Let's Encrypt production
server at https://acme-v02.api.letsencrypt.org/directory. For staging, this can be set
to https://acme-staging-v02.api.letsencrypt.org/directory.

`DOTEGE_ACME_KEY_TYPE`::
The key type to use for private keys when generating a certificate using ACME. Valid
values are:
+
  * `P256` for EC256
  * `P384` for EC384
  * `2048` for RSA-2048
  * `4096` for RSA-4096
  * `8192` for RSA-8192
+
The default value is `P384`.

`DOTEGE_SIGNAL_CONTAINER`::
The name of a container that should be sent a signal when the template or certificates
are changed. No signal is sent if not specified.

`DOTEGE_SIGNAL_TYPE`::
The type of signal to send to the `DOTEGE_SIGNAL_CONTAINER`. Defaults to `HUP`.

`DOTEGE_TEMPLATE_DESTINATION`::
Location to write the templated configuration file to. Defaults to `/data/output/haproxy.cfg`.

`DOTEGE_TEMPLATE_SOURCE`::
Path to a template to use to generate configuration. Defaults to `./templates/haproxy.cfg.tpl`,
which is a bundled basic template for generating HAProxy configurations.

`DOTEGE_WILDCARD_DOMAINS`::
A space or comma separated list of domains that should use wildcard certificates.
Defaults to an empty list.

=== Docker labels

Dotege operates by parsing labels applied to docker containers. It understands the following:

`com.chameth.auth`::
Specifies the name of an auth group (which must be defined appropriately in the template file)
that users are required to be in to access the container.

`com.chameth.proxy`::
The port on which the container is listening for requests.

`com.chameth.vhost`::
Comma- or space-delimited list of hostnames that the container will handle requests for.
Certificates will have the first host as the subject, and any additional hosts will be
alternate names. Certificates are only reused if all hostnames match.

== Example compose file

[source,yaml]
----
version: '3.5'
services:
  dotege:
    image: csmith/dotege
    restart: always
    volumes:
      - data:/data/config
      - certs:/data/certs
      - config:/data/output
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - DOTEGE_ACME_EMAIL=email@address
      - DOTEGE_DNS_PROVIDER=httpreq
      - DOTEGE_SIGNAL_CONTAINER=dotege_haproxy_1
      - DOTEGE_SIGNAL_TYPE=USR2
      - DOTEGE_WILDCARD_DOMAINS=mydomain.com
      - HTTPREQ_ENDPOINT=https://example.com/
      - HTTPREQ_USERNAME=user@name
      - HTTPREQ_PASSWORD=p@ssw0rd

  haproxy:
    image: haproxy:2.0.1
    restart: always
    volumes:
      - config:/usr/local/etc/haproxy:ro
      - certs:/certs:ro
    ports:
      - 443:443
      - 80:80
    networks:
      - web

networks:
  web:
    external: true

volumes:
  data:
  certs:
  config:
----

This creates an instance of Dotege, configured to use `httpreq` to perform DNS
operations in order to generate SSL certificates. You can see the list of
supported providers and their required environment variables in the
https://go-acme.github.io/lego/dns/[Lego docs].

The haproxy instance has read-only access to the config and certs volumes that
will be populated by Dotege, and Dotege will send it the `USR2` signal whenever
the config or certs change. With the default haproxy image this will cause it
to reload the configuration.

Container names must be resolvable from the haproxy container with the default
template. This means the haproxy container should be on the same network as
the containers it's proxying to. I recommend creating a global 'web' network
(or similar) that all web-facing containers sit in.

== Contributing

Contributions are welcome!

There is a https://pre-commit.com/[pre-commit] to go fmt and run basic checks on
commit; to enable it simply:

    pip install pre-commit
    pre-commit install