docker: skip redundant cmdeploy run on container restart

Replace the old IMAGE_VERSION_FILE/RUNNING_VERSION_FILE mechanism with a
single deploy fingerprint (image_version:sha256(chatmail.ini)) stored at
/etc/chatmail/.deploy-fingerprint. On restart, if the fingerprint matches
the last successful deploy, skip cmdeploy run entirely. The fingerprint
lives on the container's writable layer. On fresh containers, setting
CMDEPLOY_STAGES non-empty in env forces a deploy run regardless of
fingerprint.

Also narrow the /home volume mount to /home/vmail.

Author: j4n

DOCKER.md

@@ -0,0 +1,74 @@
+# Docker Setup
+
+## Image (`docker/chatmail_relay.dockerfile`)
+
+Base: `jrei/systemd-debian:12` (systemd-enabled Debian).
+
+**Build-time:** `COPY . /opt/chatmail/`, create venv at `/opt/cmdeploy/`, run `CMDEPLOY_STAGES=install` via pyinfra.
+Build needs `CHATMAIL_NOSYSCTL=True` and `CHATMAIL_NOPORTCHECK=True` since sysctl/ports aren't available during build.
+Dovecot is installed by the pyinfra install stage (not duplicated in Dockerfile).
+
+**Runtime:** systemd entrypoint, `setup_chatmail.service` runs `setup_chatmail_docker.sh` after boot.
+
+## Startup flow (`docker/files/setup_chatmail_docker.sh`)
+
+1. Validate `MAIL_DOMAIN` is set
+2. Generate DKIM keys if missing (`opendkim-genkey`)
+3. Generate `chatmail.ini` if missing (`cmdeploy init`) — skipped when volume-mounted
+4. Compute deploy fingerprint (`image_version:sha256(chatmail.ini)`) — if it matches the last successful deploy, skip `cmdeploy run` entirely (plain restart with no changes)
+5. Run `cmdeploy run --config $CHATMAIL_INI --ssh-host @local` (configure+activate stages, or install too if image version changed)
+6. Certificate monitoring handled by `chatmail-certmon.timer` (systemd timer, every 60s)
+
+## Compose (`docker-compose.yaml`)
+
+- `cgroup: host` — required for systemd (compose v2 only)
+- `network_mode: host` — no port mapping needed (see security note in compose file)
+- `.env` file: copy from `docker/example.env`, set `MAIL_DOMAIN`
+
+### Volumes
+
+| Mount | Purpose |
+|-------|---------|
+| `/sys/fs/cgroup` | systemd (required) |
+| `./data/chatmail:/home/vmail` | Mail storage (mailboxes + passdb) |
+| `./data/chatmail-dkimkeys:/etc/dkimkeys` | DKIM keys (persisted) |
+| `./data/chatmail-acme:/var/lib/acme` | ACME certs |
+| `./chatmail.ini:/etc/chatmail/chatmail.ini` | Optional: mount custom config |
+
+### Environment vars (runtime)
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `MAIL_DOMAIN` | Yes | — |
+| `CMDEPLOY_STAGES` | No | `configure,activate` |
+| `USE_FOREIGN_CERT_MANAGER` | No | — |
+
+## Config modes
+
+**Simple:** Set `MAIL_DOMAIN` in `.env`. Container generates `chatmail.ini` with defaults on first start.
+
+**Advanced:** Extract ini from running container (`docker cp chatmail:/etc/chatmail/chatmail.ini ./`), edit, mount back.
+
+## Commands inside container
+
+```shell
+docker compose exec chatmail cmdeploy dns --ssh-host @local
+docker compose exec chatmail cmdeploy status --ssh-host @local
+```
+
+`CHATMAIL_INI` env var is set in the image, so `--config` is not needed.
+
+## .dockerignore
+
+Excludes: `data/`, `venv/`, `__pycache__`, `*.pyc`, `*.orig`, `*.ini`, `.pytest_cache`, `.env`, `.git`, `.github/`, `docs/`, `tests/`, `*.md` (except `www/**/*.md`).
+
+`.git` is excluded to slim the build context. The git hash is passed via `GIT_HASH` build arg instead:
+```shell
+GIT_HASH=$(git rev-parse HEAD) docker compose build chatmail
+```
+CI sets this automatically via `github.sha`. Without it, the image version defaults to `"unknown"`.
+
+## Known issues
+
+- Kernel params (`fs.inotify.*`) must be set on the host, not in the container
+- amd64-only — no multi-arch support (deployer supports arm64 but Dockerfile doesn't)

docker-compose.yaml

@@ -41,11 +41,11 @@ services:
       ## system (required)
       - /sys/fs/cgroup:/sys/fs/cgroup:rw
       ## data (defaults — override in docker-compose.override.yaml)
-      - chatmail-mail:/home
+      - chatmail-data:/home/vmail
       - chatmail-dkimkeys:/etc/dkimkeys
       - chatmail-acme:/var/lib/acme
 
 volumes:
-  chatmail-mail:
+  chatmail-data:
   chatmail-dkimkeys:
   chatmail-acme:

docker/docker-compose.override.yaml.example

@@ -11,7 +11,7 @@ services:
       ## 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:/home/vmail
       # - ./data/chatmail-dkimkeys:/etc/dkimkeys
       # - ./data/chatmail-acme:/var/lib/acme
 

docker/files/setup_chatmail_docker.sh

@@ -18,40 +18,46 @@ fi
 # Fix ownership for bind-mounted keys (host opendkim UID may differ from container)
 chown -R opendkim:opendkim /etc/dkimkeys
 
+# Journald: forward to console for docker logs
+grep -q '^ForwardToConsole=yes' /etc/systemd/journald.conf \
+    || echo "ForwardToConsole=yes" >> /etc/systemd/journald.conf
+systemctl restart systemd-journald
+
 # Create chatmail.ini (skips if file already exists, e.g. volume-mounted)
 mkdir -p "$(dirname "$CHATMAIL_INI")"
 if [ ! -f "$CHATMAIL_INI" ]; then
     $CMDEPLOY init --config "$CHATMAIL_INI" "$MAIL_DOMAIN"
 fi
 
-# Auto-detect image upgrades: if the image version changed since last run,
-# include the install stage so new packages/binaries are picked up.
+# --- Deploy fingerprint: skip cmdeploy run if nothing changed ---
 IMAGE_VERSION_FILE="/etc/chatmail-image-version"
-RUNNING_VERSION_FILE="/home/.chatmail-running-version"
-CMDEPLOY_STAGES="${CMDEPLOY_STAGES:-configure,activate}"
-if [ -f "$IMAGE_VERSION_FILE" ]; then
-    image_ver=$(cat "$IMAGE_VERSION_FILE")
-    running_ver=""
-    if [ -f "$RUNNING_VERSION_FILE" ]; then
-        running_ver=$(cat "$RUNNING_VERSION_FILE")
-    fi
-    if [ "$image_ver" != "$running_ver" ]; then
-        echo "[INFO] Image version changed ($running_ver -> $image_ver), adding install stage."
+FINGERPRINT_FILE="/etc/chatmail/.deploy-fingerprint"
+image_ver="none"
+[ -f "$IMAGE_VERSION_FILE" ] && image_ver=$(cat "$IMAGE_VERSION_FILE")
+config_hash=$(sha256sum "$CHATMAIL_INI" | cut -c1-16)
+current_fp="${image_ver}:${config_hash}"
+
+# CMDEPLOY_STAGES non-empty in env = operator override -> always run.
+# Otherwise, if fingerprint matches the last successful deploy, skip.
+if [ -z "${CMDEPLOY_STAGES:-}" ] \
+    && [ -f "$FINGERPRINT_FILE" ] \
+    && [ "$(cat "$FINGERPRINT_FILE")" = "$current_fp" ]; then
+    echo "[INFO] No changes detected ($current_fp), skipping deploy."
+else
+    # Determine stages: default is configure,activate.
+    # If image version changed since last deploy, prepend install stage.
+    CMDEPLOY_STAGES="${CMDEPLOY_STAGES:-configure,activate}"
+    prev_fp=""
+    [ -f "$FINGERPRINT_FILE" ] && prev_fp=$(cat "$FINGERPRINT_FILE")
+    prev_image_ver="${prev_fp%%:*}"
+    if [ "$image_ver" != "$prev_image_ver" ]; then
+        echo "[INFO] Image version changed ($prev_image_ver -> $image_ver), adding install stage."
         case "$CMDEPLOY_STAGES" in
             *install*) ;;  # already includes install
             *) CMDEPLOY_STAGES="install,$CMDEPLOY_STAGES" ;;
         esac
     fi
+    export CMDEPLOY_STAGES
+    $CMDEPLOY run --config "$CHATMAIL_INI" --ssh-host @local
+    echo "$current_fp" > "$FINGERPRINT_FILE"
 fi
-export CMDEPLOY_STAGES
-$CMDEPLOY run --config "$CHATMAIL_INI" --ssh-host @local
-
-# Record successful version after deploy
-if [ -f "$IMAGE_VERSION_FILE" ]; then
-    cp "$IMAGE_VERSION_FILE" "$RUNNING_VERSION_FILE"
-fi
-
-# Journald: forward to console for docker logs (idempotent)
-grep -q '^ForwardToConsole=yes' /etc/systemd/journald.conf \
-    || echo "ForwardToConsole=yes" >> /etc/systemd/journald.conf
-systemctl restart systemd-journald