Docker template generator
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.
Chris Smith 694fed0f58
Update go and random dependencies.
пре 4 година
templates Add some colons to try and make V6 work again пре 4 година
.gitignore Initial import пре 5 година
.pre-commit-config.yaml Use new docker and lego code пре 5 година
Dockerfile Use new docker and lego code пре 5 година
LICENCE Add licence пре 5 година
README.adoc Flesh out readme a little пре 4 година
config.go Update go and random dependencies. пре 4 година
config_test.go Initialise config immediately пре 5 година
docker.go Remove dead code, tidy up пре 5 година
dotege.go Maybe don't name all certs '*.pem' пре 5 година
dotege_test.go Initialise config immediately пре 5 година
go.mod Update go and random dependencies. пре 4 година
go.sum Update go and random dependencies. пре 4 година
lego.go Update go and random dependencies. пре 4 година
lego_test.go Accept existing certs in any order пре 5 година
templates.go Remove dead code, tidy up пре 5 година

README.adoc

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