From c22efeb74ba2a1a99fc4a2675f590427e0b5b08c Mon Sep 17 00:00:00 2001
From: j4n <j4n@systemli.org>
Date: Tue, 17 Feb 2026 07:53:18 +0100
Subject: [PATCH] docker: use docker-compose.override.yaml for user
 customizations

The base docker-compose.yaml was checked into git and thus would get
overwritten on pull.
- docker-compose.yaml uses named volumes as safe defaults
- docker-compose.override.yaml (gitignored) holds user customizations
- Compose automatically merges both files
---
 .gitignore                                  |  1 +
 docker-compose.yaml                         | 28 +++++++++-----------
 docker/docker-compose.override.yaml.example | 29 +++++++++++++++++++++
 docs/DOCKER_INSTALLATION_EN.md              | 12 ++++++---
 4 files changed, 51 insertions(+), 19 deletions(-)
 create mode 100644 docker/docker-compose.override.yaml.example

diff --git a/.gitignore b/.gitignore
index da7cd1c8..3d197fa5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -168,4 +168,5 @@ chatmail.zone
 # docker
 /data/
 /custom/
+docker-compose.override.yaml
 .env
diff --git a/docker-compose.yaml b/docker-compose.yaml
index c3fb6a4b..487b24d8 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -1,4 +1,6 @@
-# Copy docker/example.env to .env and set MAIL_DOMAIN before starting.
+# Base compose file — do not edit. Put customizations (data paths, extra
+# volumes, env overrides) in docker-compose.override.yaml instead.
+# See docker/docker-compose.override.yaml.example for a starting point.
 #
 # Security note: this container uses network_mode:host (chatmail needs many
 # ports: 25, 53, 80, 143, 443, 465, 587, 993, 3340, 8443) and cgroup:host
@@ -32,18 +34,14 @@ services:
       CHATMAIL_NOACME: ${CHATMAIL_NOACME:-}
     network_mode: "host"
     volumes:
-      ## system
-      - /sys/fs/cgroup:/sys/fs/cgroup:rw # required for systemd
+      ## system (required)
+      - /sys/fs/cgroup:/sys/fs/cgroup:rw
+      ## data (defaults — override in docker-compose.override.yaml)
+      - chatmail-mail:/home
+      - chatmail-dkimkeys:/etc/dkimkeys
+      - chatmail-acme:/var/lib/acme
 
-      ## data
-      - ./data/chatmail:/home
-      - ./data/chatmail-dkimkeys:/etc/dkimkeys
-      - ./data/chatmail-acme:/var/lib/acme
-
-      ## optional overrides
-      # - ./chatmail.ini:/etc/chatmail/chatmail.ini   # use your own config
-      # - ./custom/www:/opt/chatmail-www              # custom website
-
-      ## debug
-      # - ./docker/files/setup_chatmail_docker.sh:/setup_chatmail_docker.sh
-      # - ./docker/files/entrypoint.sh:/entrypoint.sh
+volumes:
+  chatmail-mail:
+  chatmail-dkimkeys:
+  chatmail-acme:
diff --git a/docker/docker-compose.override.yaml.example b/docker/docker-compose.override.yaml.example
new file mode 100644
index 00000000..21d6e203
--- /dev/null
+++ b/docker/docker-compose.override.yaml.example
@@ -0,0 +1,29 @@
+# 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
+#
+# Volumes listed here are APPENDED to the base file's volumes.
+# Scalar values (environment, image, etc.) are REPLACED.
+services:
+  chatmail:
+    volumes:
+      ## Data paths — bind-mount to host directories for easy access/backup.
+      ## Uncomment and adjust paths as needed. These override the named
+      ## volumes in the base docker-compose.yaml.
+      # - ./data/chatmail:/home
+      # - ./data/chatmail-dkimkeys:/etc/dkimkeys
+      # - ./data/chatmail-acme:/var/lib/acme
+
+      ## Or mount mail storage from an existing bare-metal install:
+      # - /home/vmail:/home/vmail
+
+      ## Mount your own chatmail.ini (skips auto-generation):
+      # - ./chatmail.ini:/etc/chatmail/chatmail.ini
+
+      ## Custom website:
+      # - ./custom/www:/opt/chatmail-www
+
+      ## 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
diff --git a/docs/DOCKER_INSTALLATION_EN.md b/docs/DOCKER_INSTALLATION_EN.md
index 70becb03..7b862429 100644
--- a/docs/DOCKER_INSTALLATION_EN.md
+++ b/docs/DOCKER_INSTALLATION_EN.md
@@ -74,6 +74,12 @@ If you are running from the cloned repo directory, just copy the env file:
 
 ```shell
 cp ./docker/example.env .env
+```
+
+   All local customizations (data paths, extra volumes, config mounts) go in `docker-compose.override.yaml`, which Compose merges automatically with the base file. Copy the example to get started:
+
+```shell
+cp docker/docker-compose.override.yaml.example docker-compose.override.yaml
 ```
 
 2. Configure the `.env` file. Only `MAIL_DOMAIN` is required:
@@ -120,13 +126,12 @@ mkdir -p ./custom/www/src
 nano ./custom/www/src/index.md
 ```
 
-2. In `docker-compose.yaml`, uncomment or add the website volume mount:
+2. Add the volume mount in `docker-compose.override.yaml`:
 
 ```yaml
 services:
   chatmail:
     volumes:
-      ...
       - ./custom/www:/opt/chatmail-www
 ```
 
@@ -153,13 +158,12 @@ docker cp chatmail:/etc/chatmail/chatmail.ini ./chatmail.ini
 
 2. Edit `chatmail.ini` as needed.
 
-3. In `docker-compose.yaml`, uncomment or add the ini volume mount:
+3. Add the volume mount in `docker-compose.override.yaml`:
 
 ```yaml
 services:
   chatmail:
     volumes:
-      ...
       - ./chatmail.ini:/etc/chatmail/chatmail.ini
 ```