docker: streamline overrides, rename datadirs, external TLS

doc/source/docker.rst

@@ -60,39 +60,32 @@ Either:
 - Create a service directory, e.g., `/srv/chatmail-relay`::
 
     mkdir -p /srv/chatmail-relay && cd /srv/chatmail-relay
-    wget https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker-compose.yaml https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker-compose.override.yaml.example
+    wget https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker-compose.yaml
-    wget https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker/env.example -O .env
+    wget https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker-compose.override.yaml.example -O docker-compose.override.yaml
-    
 
 - or clone the chatmail repo ::
 
    git clone https://github.com/chatmail/relay
    cd relay
-   cp example.env .env
-
 
 
 Customize and start
 ^^^^^^^^^^^^^^^^^^^
 
-1. All local customizations (data paths, extra volumes, config mounts) go in
+1. Set the fully qualified domain name of the relay::
-   ``docker-compose.override.yaml``, which Compose merges automatically with
-   the base file. By default, all data is stored in docker volumes, you will
-   likely want to at least create and configure the mail storage location. Copy
-   the example to get started::
 
-       cp docker/docker-compose.override.yaml.example docker-compose.override.yaml
+       echo 'MAIL_DOMAIN=chat.example.org' > .env
-       # and edit docker-compose.override.yaml
-
-
-
-2. Configure the ``.env`` file. Only ``MAIL_DOMAIN`` is required, the domain
-   name of the future server.
 
    The container generates a ``chatmail.ini`` with defaults from
    ``MAIL_DOMAIN`` on first start. To customize chatmail settings, mount
    your own ``chatmail.ini`` instead (see `Custom chatmail.ini`_ below).
 
+2. All local customizations (data paths, extra volumes, config mounts) go in
+   ``docker-compose.override.yaml``, which Compose merges automatically with
+   the base file. By default, all data is stored in docker volumes, you will
+   likely want to at least create and configure the mail storage location, but
+   you might also want to configure external TLS certificates there.
+
 3. Start the container::
 
        docker compose up -d
@@ -101,26 +94,36 @@ Customize and start
 4. After installation is complete, open ``https://chat.example.org`` in
    your browser.
 
+Finish install and test
+-----------------------
 
-Managing the server
+You can test the installation with::
--------------------
 
-Use ``docker exec`` to run cmdeploy commands inside the container::
+        pip install cmping chat.example.org # or
+        uvx cmping chat.example.org # if you use https://docs.astral.sh/uv/
+
+You should check and extend your DNS records for better interoperability::
 
     # Show required DNS records
     docker exec chatmail /opt/cmdeploy/bin/cmdeploy dns --ssh-host @local
 
-    # Check server status
+You can check server status with::
+
     docker exec chatmail /opt/cmdeploy/bin/cmdeploy status --ssh-host @local
 
-    # Run benchmarks (can also run from any machine with cmdeploy installed)
+You can run some benchmarks (can also run from any machine with cmdeploy installed)
+
     docker exec chatmail /opt/cmdeploy/bin/cmdeploy bench chat.example.org
 
+You can run the test suite with
+
+    docker exec chatmail /opt/cmdeploy/bin/cmdeploy test chat.example.org --ssh-host localhost
+
 
 Customization
 -------------
 
-Custom website
+Website
 ^^^^^^^^^^^^^^
 
 You can customize the chatmail landing page by mounting a directory with
@@ -147,14 +150,8 @@ your own website source files.
 Custom chatmail.ini
 ^^^^^^^^^^^^^^^^^^^
 
-There are two configuration modes:
+If you want to go beyond simply setting the ``MAIL_DOMAIN`` in ``.env``, you
-
+can use a regular `chatmail.ini` to give you full control.
-**Simple (default):** Set ``MAIL_DOMAIN`` in ``.env``. The container
-auto-generates ``chatmail.ini`` with defaults on first start. This is
-sufficient for most deployments.
-
-**Advanced:** Generate a ``chatmail.ini``, edit it, and mount it into
-the container. This gives you full control over all chatmail settings.
 
 1. Extract the generated config from a running container::
 
@@ -174,6 +171,16 @@ the container. This gives you full control over all chatmail settings.
        docker compose down && docker compose up -d
 
 
+External TLS certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If TLS certificates are managed outside the container (e.g. by certbot,
+acmetool, or Traefik on the host), mount them into the container and set
+``TLS_EXTERNAL_CERT_AND_KEY`` in ``docker-compose.override.yaml``.
+Changed certificates are picked up automatically via inotify.
+See the examples in the example override and :ref:`external-tls` in the getting started guide for details.
+
+
 Migrating from a bare-metal install
 ------------------------------------
 
@@ -196,16 +203,19 @@ switch to Docker:
 
 3. Copy persistent data into the ``./data/`` subdirectories (for example, as configured in `Customize and start`_) ::
 
-       mkdir -p data/chatmail-dkimkeys data/chatmail-acme data/chatmail
+       mkdir -p data/dkim data/certs data/mail
 
        # DKIM keys
-       cp -a /etc/dkimkeys/* data/chatmail-dkimkeys/
+       cp -a /etc/dkimkeys/* data/dkim/
 
-       # ACME certificates and account
+       # TLS certificates
-       rsync -a /var/lib/acme/ data/chatmail-acme/
+       rsync -a /var/lib/acme/ data/certs/
 
-       # Mail data
+   Note that ownership of dkim and acme is adjusted on container start.
-       rsync -a /home/ data/chatmail/
+
+   For the mail directory::
+
+       rsync -a /home/vmail/ data/mail/
 
    Alternatively, mount ``/home/vmail`` directly by changing the volume
    in ``docker-compose-override.yaml``::
@@ -226,8 +236,8 @@ Clone the repository and build the Docker image::
     docker compose build chatmail
 
 The build bakes all binaries, Python packages, and the install stage
-into the image. After building, only ``docker-compose.yaml`` and ``.env``
+into the image. After building, only ``docker-compose.yaml`` and a ``.env`` with
-are needed to run the container.
+``MAIL_DOMAIN`` are needed to run the container.
 
 You can transfer a locally built image to your server directly (pigz is parallel `gzip` which can be used instead as well) ::
 

docker-compose.override.yaml.example

@@ -1,37 +1,20 @@
 # Local overrides — copy to docker-compose.override.yaml in the repo root.
 # Compose automatically merges this with docker-compose.yaml.
 #
-#   cp docker/docker-compose.override.yaml.example docker-compose.override.yaml
+#   cp docker-compose.override.yaml.example docker-compose.override.yaml
 #
-# Volumes listed here are APPENDED to the base file's volumes.
+# Volumes are APPENDED to the base file's volumes list.
-# Scalar values (environment, image, etc.) are REPLACED.
+# Environment and other scalar keys are MERGED by key.
-#
-# --- External TLS certificates ---
-# Use when certs are managed outside the container (certbot, acmetool, Traefik, ...).
-# Mount the cert files and set TLS_EXTERNAL_CERT_AND_KEY to the in-container paths.
-# Changed certs are picked up automatically (inotify via tls-cert-reload.path).
-#
-# Host acmetool (bare-metal migration):
-#   volumes:  - /var/lib/acme/live:/var/lib/acme/live:ro
-#   environment:
-#     TLS_EXTERNAL_CERT_AND_KEY: "/var/lib/acme/live/${MAIL_DOMAIN}/fullchain /var/lib/acme/live/${MAIL_DOMAIN}/privkey"
-#
-# Traefik certs-dumper (see docker/docker-compose-traefik.yaml):
-#   volumes:  - traefik-certs:/certs:ro
-#   environment:
-#     TLS_EXTERNAL_CERT_AND_KEY: "/certs/${MAIL_DOMAIN}/certificate.crt /certs/${MAIL_DOMAIN}/privatekey.key"
-
 services:
   chatmail:
     volumes:
       ## Data paths — bind-mount to host directories for easy access/backup.
-      ## Uncomment and adjust paths as needed. These override the named
+      ## These override the named volumes in the base docker-compose.yaml.
-      ## volumes in the base docker-compose.yaml.
+      # - ./data/mail:/home/vmail
-      # - ./data/chatmail:/home/vmail
+      # - ./data/dkim:/etc/dkimkeys
-      # - ./data/chatmail-dkimkeys:/etc/dkimkeys
+      # - ./data/certs:/var/lib/acme
-      # - ./data/chatmail-acme:/var/lib/acme
 
-      ## Or mount data from an existing bare-metal install.
+      ## Or mount from an existing bare-metal install.
       ## Note: DKIM key ownership is fixed automatically on startup
       ## (the host's opendkim UID may differ from the container's).
       # - /home/vmail:/home/vmail
@@ -47,3 +30,16 @@ services:
       ## Debug — mount scripts from the repo for live editing:
       # - ./docker/files/setup_chatmail_docker.sh:/setup_chatmail_docker.sh
       # - ./docker/files/entrypoint.sh:/entrypoint.sh
+
+    # environment:
+      ## --- External TLS certificates ---
+      ## Mount certs (above) and set TLS_EXTERNAL_CERT_AND_KEY to in-container paths.
+      ## Changed certs are picked up automatically (inotify via tls-cert-reload.path).
+      ##
+      ## Host acmetool (bare-metal migration) — also add volume:
+      ##   - /var/lib/acme/live:/var/lib/acme/live:ro
+      # TLS_EXTERNAL_CERT_AND_KEY: "/var/lib/acme/live/${MAIL_DOMAIN}/fullchain /var/lib/acme/live/${MAIL_DOMAIN}/privkey"
+      ##
+      ## Traefik certs-dumper (see docker/docker-compose-traefik.yaml) — also add volume:
+      ##   - traefik-certs:/certs:ro
+      # TLS_EXTERNAL_CERT_AND_KEY: "/certs/${MAIL_DOMAIN}/certificate.crt /certs/${MAIL_DOMAIN}/privatekey.key"

docker-compose.yaml

@@ -32,20 +32,18 @@ services:
         max-file: "3"
     environment:
       MAIL_DOMAIN: $MAIL_DOMAIN
-      CMDEPLOY_STAGES: ${CMDEPLOY_STAGES:-}
       CHATMAIL_NOSYSCTL: ${CHATMAIL_NOSYSCTL:-True}
       CHATMAIL_NOPORTCHECK: ${CHATMAIL_NOPORTCHECK:-True}
-      TLS_EXTERNAL_CERT_AND_KEY: ${TLS_EXTERNAL_CERT_AND_KEY:-}
     network_mode: "host"
     volumes:
       ## system (required)
       - /sys/fs/cgroup:/sys/fs/cgroup:rw
       ## data (defaults — override in docker-compose.override.yaml)
-      - chatmail-data:/home/vmail
+      - mail:/home/vmail
-      - chatmail-dkimkeys:/etc/dkimkeys
+      - dkim:/etc/dkimkeys
-      - chatmail-acme:/var/lib/acme
+      - certs:/var/lib/acme
 
 volumes:
-  chatmail-data:
+  mail:
-  chatmail-dkimkeys:
+  dkim:
-  chatmail-acme:
+  certs:

env.example

@@ -1,9 +1 @@
-MAIL_DOMAIN="chat.example.com"
+MAIL_DOMAIN=chat.example.com
-
-# CMDEPLOY_STAGES - default: "configure,activate". Set to "install,configure,activate" to force full reinstall.
-# CMDEPLOY_STAGES="configure,activate"
-
-# External TLS certificates (e.g. from Traefik, Caddy, certbot on the host).
-# Paths refer to locations *inside* the container.
-# Mount the cert files via a volume (see docker-compose.override.yaml.example).
-# TLS_EXTERNAL_CERT_AND_KEY="/certs/fullchain.pem /certs/privkey.pem"