docker/chatmail-init.sh: disable port check its more hassle than its worth

- use local execute on both
- re-use VMs for docker tests
- bring back GHCR builds and use for deployments (offloads VMs, allows
  caching, but may be rate-limited)

.dockerignore

@@ -0,0 +1,18 @@
+data/
+venv/
+__pycache__
+*.pyc
+*.orig
+*.ini
+.pytest_cache
+.env
+
+# Slim build context — .git/ alone can be 100s of MB
+.git
+.github/
+docs/
+tests/
+
+# Exclude markdown files but keep www/src/*.md (used by WebsiteDeployer)
+*.md
+!www/**/*.md

.github/workflows/ci.yaml

@@ -15,7 +15,7 @@ jobs:
         with:
           ref: ${{ github.event.pull_request.head.sha }}
       - name: download filtermail
-        run: curl -L https://github.com/chatmail/filtermail/releases/download/v0.3.0/filtermail-x86_64 -o /usr/local/bin/filtermail && chmod +x /usr/local/bin/filtermail
+        run: curl -L https://github.com/chatmail/filtermail/releases/download/v0.5.2/filtermail-x86_64 -o /usr/local/bin/filtermail && chmod +x /usr/local/bin/filtermail
       - name: run chatmaild tests 
         working-directory: chatmaild
         run: pipx run tox

.github/workflows/deploy.yaml

@@ -0,0 +1,375 @@
+name: Deploy
+
+on:
+  push:
+    branches:
+      - main
+      - j4n/docker-pr
+  pull_request:
+    paths-ignore:
+      - 'scripts/**'
+      - '**/README.md'
+      - 'CHANGELOG.md'
+      - 'LICENSE'
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-docker:
+    name: Build Docker image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      image: ${{ steps.image-ref.outputs.image }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            # Tagged releases: v1.2.3 -> :1.2.3, :1.2, :latest
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            # Branch pushes: foo/docker-pr -> :foo-docker-pr
+            type=ref,event=branch
+            # Always: :sha-<hash>
+            type=sha
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/chatmail_relay.dockerfile
+          push: ${{ github.event_name == 'push' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            GIT_HASH=${{ github.sha }}
+
+      - name: Output image reference
+        id: image-ref
+        run: |
+          SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
+          IMAGE="${{ env.REGISTRY }}/$(echo "${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]'):sha-${SHORT_SHA}"
+          echo "image=${IMAGE}" >> "$GITHUB_OUTPUT"
+
+  deploy:
+    name: Deploy to ${{ matrix.host }}
+    needs: build-docker
+    # dont do the regular tests on this branch
+    if: >-
+      !cancelled() && (
+        github.event_name == 'push' ||
+        (github.event_name == 'pull_request' && !startsWith(github.head_ref, 'j4n/'))
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - host: staging2.testrun.org
+            acme_dir: acme
+            dkim_dir: dkimkeys
+            zone_file: staging.testrun.org-default.zone
+            disable_ipv6: false
+            add_ssh_keys: true
+          - host: staging-ipv4.testrun.org
+            acme_dir: acme-ipv4
+            dkim_dir: dkimkeys-ipv4
+            zone_file: staging-ipv4.testrun.org-default.zone
+            disable_ipv6: true
+            add_ssh_keys: false
+    environment:
+      name: ${{ matrix.host }}
+      url: https://${{ matrix.host }}/
+    concurrency: ${{ matrix.host }}
+    steps:
+      # --- Common setup ---
+
+      - uses: actions/checkout@v4
+
+      - name: prepare SSH and save ACME/DKIM
+        env:
+          HOST: ${{ matrix.host }}
+          ACME_DIR: ${{ matrix.acme_dir }}
+          DKIM_DIR: ${{ matrix.dkim_dir }}
+          ZONE: ${{ matrix.zone_file }}
+        run: |
+          mkdir ~/.ssh
+          echo "${{ secrets.STAGING_SSH_KEY }}" >> ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          ssh-keyscan ${HOST} > ~/.ssh/known_hosts
+          # save previous acme & dkim state (trailing slash = copy contents)
+          rsync -avz root@${HOST}:/var/lib/acme/ ${ACME_DIR}/ || true
+          rsync -avz root@${HOST}:/etc/dkimkeys/ ${DKIM_DIR}/ || true
+          # backup to ns.testrun.org if contents are useful
+          if [ -f ${DKIM_DIR}/opendkim.private ]; then
+            rsync -avz -e "ssh -o StrictHostKeyChecking=accept-new" ${DKIM_DIR}/ root@ns.testrun.org:/tmp/${DKIM_DIR}/ || true
+          fi
+          if [ "$(ls -A ${ACME_DIR}/certs 2>/dev/null)" ]; then
+            rsync -avz -e "ssh -o StrictHostKeyChecking=accept-new" ${ACME_DIR}/ root@ns.testrun.org:/tmp/${ACME_DIR}/ || true
+          fi
+          # make sure CAA record isn't set
+          scp -o StrictHostKeyChecking=accept-new .github/workflows/${ZONE} root@ns.testrun.org:/etc/nsd/${HOST}.zone
+          ssh root@ns.testrun.org sed -i '/CAA/d' /etc/nsd/${HOST}.zone
+          ssh root@ns.testrun.org nsd-checkzone ${HOST} /etc/nsd/${HOST}.zone
+          ssh root@ns.testrun.org systemctl reload nsd
+
+      - name: rebuild VPS
+        env:
+          SERVER_ID: ${{ matrix.host == 'staging2.testrun.org' && secrets.STAGING_SERVER_ID || secrets.STAGING_IPV4_SERVER_ID }}
+        run: |
+          curl -X POST \
+            -H "Authorization: Bearer ${{ secrets.HETZNER_API_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d '{"image":"debian-12"}' \
+            "https://api.hetzner.cloud/v1/servers/${SERVER_ID}/actions/rebuild"
+
+      - run: scripts/initenv.sh
+      - name: append venv/bin to PATH
+        run: echo venv/bin >>$GITHUB_PATH
+
+      - name: wait for VPS rebuild
+        id: wait-for-vps
+        env:
+          HOST: ${{ matrix.host }}
+        run: |
+          rm ~/.ssh/known_hosts
+          while ! ssh -o ConnectTimeout=180 -o StrictHostKeyChecking=accept-new root@${HOST} id -u ; do sleep 1 ; done
+
+      - name: restore ACME/DKIM
+        env:
+          HOST: ${{ matrix.host }}
+          ACME_DIR: ${{ matrix.acme_dir }}
+          DKIM_DIR: ${{ matrix.dkim_dir }}
+        run: |
+          # download from ns.testrun.org
+          rsync -e "ssh -o StrictHostKeyChecking=accept-new" -avz root@ns.testrun.org:/tmp/${ACME_DIR}/ acme-restore/ || true
+          rsync -avz root@ns.testrun.org:/tmp/${DKIM_DIR}/ dkimkeys-restore/ || true
+          # restore to VPS
+          rsync -avz acme-restore/ root@${HOST}:/var/lib/acme/ || true
+          rsync -avz dkimkeys-restore/ root@${HOST}:/etc/dkimkeys/ || true
+          ssh root@${HOST} chown root:root -R /var/lib/acme || true
+
+      - name: bare offline tests
+        if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
+        run: pytest --pyargs cmdeploy
+
+      - name: bare deploy
+        if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
+        env:
+          HOST: ${{ matrix.host }}
+          DISABLE_IPV6: ${{ matrix.disable_ipv6 }}
+        run: |
+          ssh root@${HOST} 'apt update && apt install -y git python3.11-venv python3-dev gcc'
+          ssh root@${HOST} 'git clone https://github.com/chatmail/relay'
+          ssh root@${HOST} "cd relay && git checkout ${{ github.head_ref || github.ref_name }}"
+          ssh root@${HOST} 'cd relay && scripts/initenv.sh'
+          ssh root@${HOST} "cd relay && scripts/cmdeploy init ${HOST}"
+          if [ "${DISABLE_IPV6}" = "true" ]; then
+            ssh root@${HOST} "sed -i 's#disable_ipv6 = False#disable_ipv6 = True#' relay/chatmail.ini"
+          fi
+          ssh root@${HOST} "sed -i 's/#\s*mtail_address/mtail_address/' relay/chatmail.ini"
+          ssh root@${HOST} "cd relay && scripts/cmdeploy run --verbose --skip-dns-check --ssh-host localhost"
+
+      - name: bare DNS
+        if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
+        env:
+          HOST: ${{ matrix.host }}
+          ZONE: ${{ matrix.zone_file }}
+        run: |
+          ssh root@${HOST} chown opendkim:opendkim -R /etc/dkimkeys
+          ssh root@${HOST} "cd relay && scripts/cmdeploy dns --zonefile staging-generated.zone --ssh-host localhost"
+          ssh root@${HOST} cat relay/staging-generated.zone >> .github/workflows/${ZONE}
+          cat .github/workflows/${ZONE}
+          scp .github/workflows/${ZONE} root@ns.testrun.org:/etc/nsd/${HOST}.zone
+          ssh root@ns.testrun.org nsd-checkzone ${HOST} /etc/nsd/${HOST}.zone
+          ssh root@ns.testrun.org systemctl reload nsd
+
+      - name: bare integration tests
+        if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
+        env:
+          HOST: ${{ matrix.host }}
+        run: ssh root@${HOST} "cd relay && CHATMAIL_DOMAIN2=ci-chatmail.testrun.org scripts/cmdeploy test --slow --ssh-host localhost"
+
+      - name: bare final DNS check
+        if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
+        env:
+          HOST: ${{ matrix.host }}
+        run: ssh root@${HOST} "cd relay && scripts/cmdeploy dns -v --ssh-host localhost"
+
+      # --- Docker deploy (push only, runs even if bare failed) ---
+
+      - name: stop bare services
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        env:
+          HOST: ${{ matrix.host }}
+        run: |
+          ssh root@${HOST} 'systemctl stop postfix dovecot nginx opendkim unbound filtermail doveauth chatmail-metadata iroh-relay mtail fcgiwrap acmetool 2>/dev/null || true'
+
+      - name: install Docker on VPS
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        env:
+          HOST: ${{ matrix.host }}
+        run: |
+          ssh root@${HOST} 'apt-get update && apt-get install -y ca-certificates curl'
+          ssh root@${HOST} 'install -m 0755 -d /etc/apt/keyrings'
+          ssh root@${HOST} 'curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc && chmod a+r /etc/apt/keyrings/docker.asc'
+          ssh root@${HOST} 'echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo $VERSION_CODENAME) stable" > /etc/apt/sources.list.d/docker.list'
+          ssh root@${HOST} 'apt-get update && apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin'
+
+      - name: prepare Docker bind mounts
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        env:
+          HOST: ${{ matrix.host }}
+        run: |
+          ssh root@${HOST} 'mkdir -p /srv/chatmail/certs /srv/chatmail/dkim'
+          ssh root@${HOST} 'cp -a /var/lib/acme/. /srv/chatmail/certs/ && cp -a /etc/dkimkeys/. /srv/chatmail/dkim/' || true
+
+      - name: generate and upload chatmail.ini
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        env:
+          HOST: ${{ matrix.host }}
+        run: |
+          cmdeploy init ${HOST}
+          sed -i 's/#\s*mtail_address/mtail_address/' chatmail.ini
+          scp chatmail.ini root@${HOST}:/srv/chatmail/chatmail.ini
+
+      - name: deploy with Docker
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        env:
+          HOST: ${{ matrix.host }}
+        run: |
+          GHCR_IMAGE="${{ needs.build-docker.outputs.image }}"
+          rsync -avz --exclude='.git' --exclude='venv' --exclude='__pycache__' ./ root@${HOST}:/srv/chatmail/relay/
+          # Login to GHCR on VPS and pull pre-built image
+          echo "${{ secrets.GITHUB_TOKEN }}" | ssh root@${HOST} 'docker login ghcr.io -u ${{ github.actor }} --password-stdin'
+          ssh root@${HOST} "docker pull ${GHCR_IMAGE}"
+          ssh root@${HOST} "cd /srv/chatmail/relay && CHATMAIL_IMAGE=${GHCR_IMAGE} MAIL_DOMAIN=${HOST} docker compose -f docker-compose.yaml -f docker/docker-compose.ci.yaml up -d"
+
+      - name: wait for container healthy
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        env:
+          HOST: ${{ matrix.host }}
+        run: |
+          # Stream journald inside the container
+          ssh root@${HOST} 'docker exec chatmail journalctl -f --no-pager' &
+          LOG_PID=$!
+          trap "kill $LOG_PID 2>/dev/null || true" EXIT
+          for i in $(seq 1 60); do
+            status=$(ssh root@${HOST} 'docker inspect --format={{.State.Health.Status}} chatmail 2>/dev/null' || echo "missing")
+            echo "  [$i/60] status=$status"
+            if [ "$status" = "healthy" ]; then
+              echo "Container is healthy."
+              exit 0
+            fi
+            if [ "$status" = "unhealthy" ]; then
+              echo "Container is unhealthy!"
+              break
+            fi
+            sleep 5
+          done
+          echo "Container did not become healthy."
+          kill $LOG_PID 2>/dev/null || true
+          echo "--- failed units ---"
+          ssh root@${HOST} 'docker exec chatmail systemctl --failed --no-pager' || true
+          echo "--- service logs ---"
+          ssh root@${HOST} 'docker exec chatmail journalctl -u dovecot -u postfix -u nginx -u unbound --no-pager -n 50' || true
+          echo "--- listening ports ---"
+          ssh root@${HOST} 'docker exec chatmail ss -tlnp' || true
+          echo "--- chatmail.ini ---"
+          ssh root@${HOST} 'docker exec chatmail cat /etc/chatmail/chatmail.ini' || true
+          exit 1
+
+      - name: show container state
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        env:
+          HOST: ${{ matrix.host }}
+        run: |
+          echo "--- listening ports ---"
+          ssh root@${HOST} 'docker exec chatmail ss -tlnp'
+          echo "--- chatmail.ini ---"
+          ssh root@${HOST} 'docker exec chatmail cat /etc/chatmail/chatmail.ini'
+
+      - name: Docker offline tests
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        run: CHATMAIL_DOCKER=chatmail pytest --pyargs cmdeploy
+
+      - name: Docker DNS
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        env:
+          HOST: ${{ matrix.host }}
+          ZONE: ${{ matrix.zone_file }}
+        run: |
+          # Reset zone file in case bare DNS already appended to it
+          git checkout .github/workflows/${ZONE}
+          ssh root@${HOST} 'docker exec chatmail chown opendkim:opendkim -R /etc/dkimkeys'
+          ssh root@${HOST} 'docker exec chatmail cmdeploy dns --ssh-host @local --zonefile /opt/chatmail/staging.zone --verbose'
+          ssh root@${HOST} 'docker cp chatmail:/opt/chatmail/staging.zone /tmp/staging.zone'
+          scp root@${HOST}:/tmp/staging.zone staging-generated.zone
+          cat staging-generated.zone >> .github/workflows/${ZONE}
+          cat .github/workflows/${ZONE}
+          scp .github/workflows/${ZONE} root@ns.testrun.org:/etc/nsd/${HOST}.zone
+          ssh root@ns.testrun.org nsd-checkzone ${HOST} /etc/nsd/${HOST}.zone
+          ssh root@ns.testrun.org systemctl reload nsd
+
+      - name: Docker integration tests
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        run: CHATMAIL_DOCKER=chatmail CHATMAIL_DOMAIN2=ci-chatmail.testrun.org cmdeploy test --slow
+
+      - name: Docker final DNS check
+        if: >-
+          !cancelled() && github.event_name == 'push'
+          && steps.wait-for-vps.outcome == 'success'
+        env:
+          HOST: ${{ matrix.host }}
+        run: ssh root@${HOST} 'docker exec chatmail cmdeploy dns -v --ssh-host @local'
+
+      # --- Cleanup ---
+
+      - name: add SSH keys
+        if: >-
+          !cancelled() && matrix.add_ssh_keys
+          && steps.wait-for-vps.outcome == 'success'
+        run: ssh root@${{ matrix.host }} 'curl -s https://github.com/hpk42.keys https://github.com/j4n.keys >> .ssh/authorized_keys'

.github/workflows/test-and-deploy-ipv4only.yaml

@@ -1,105 +0,0 @@
-name: deploy on staging-ipv4.testrun.org, and run tests
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    paths-ignore:
-      - 'scripts/**'
-      - '**/README.md'
-      - 'CHANGELOG.md'
-      - 'LICENSE'
-
-jobs:
-  deploy:
-    name: deploy on staging-ipv4.testrun.org, and run tests
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    environment:
-      name: staging-ipv4.testrun.org
-      url: https://staging-ipv4.testrun.org/
-    concurrency: staging-ipv4.testrun.org
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: prepare SSH
-        run: |
-          mkdir ~/.ssh
-          echo "${{ secrets.STAGING_SSH_KEY }}" >> ~/.ssh/id_ed25519
-          chmod 600 ~/.ssh/id_ed25519
-          ssh-keyscan staging-ipv4.testrun.org > ~/.ssh/known_hosts
-          # save previous acme & dkim state
-          rsync -avz root@staging-ipv4.testrun.org:/var/lib/acme acme-ipv4 || true
-          rsync -avz root@staging-ipv4.testrun.org:/etc/dkimkeys dkimkeys-ipv4 || true
-          # store previous acme & dkim state on ns.testrun.org, if it contains useful certs
-          if [ -f dkimkeys-ipv4/dkimkeys/opendkim.private ]; then rsync -avz -e "ssh -o StrictHostKeyChecking=accept-new" dkimkeys-ipv4 root@ns.testrun.org:/tmp/ || true; fi
-          if [ "$(ls -A acme-ipv4/acme/certs)" ]; then rsync -avz -e "ssh -o StrictHostKeyChecking=accept-new" acme-ipv4 root@ns.testrun.org:/tmp/ || true; fi
-          # make sure CAA record isn't set
-          scp -o StrictHostKeyChecking=accept-new .github/workflows/staging-ipv4.testrun.org-default.zone root@ns.testrun.org:/etc/nsd/staging-ipv4.testrun.org.zone
-          ssh root@ns.testrun.org sed -i '/CAA/d' /etc/nsd/staging-ipv4.testrun.org.zone
-          ssh root@ns.testrun.org nsd-checkzone staging-ipv4.testrun.org /etc/nsd/staging-ipv4.testrun.org.zone
-          ssh root@ns.testrun.org systemctl reload nsd
-
-      - name: rebuild staging-ipv4.testrun.org to have a clean VPS
-        run: |
-            curl -X POST \
-            -H "Authorization: Bearer ${{ secrets.HETZNER_API_TOKEN }}" \
-            -H "Content-Type: application/json" \
-            -d '{"image":"debian-12"}' \
-            "https://api.hetzner.cloud/v1/servers/${{ secrets.STAGING_IPV4_SERVER_ID }}/actions/rebuild"
-
-      - run: scripts/initenv.sh
-
-      - name: append venv/bin to PATH
-        run: echo venv/bin >>$GITHUB_PATH
-
-      - name: upload TLS cert after rebuilding
-        run: |
-          echo " --- wait until staging-ipv4.testrun.org VPS is rebuilt --- "
-          rm ~/.ssh/known_hosts
-          while ! ssh -o ConnectTimeout=180 -o StrictHostKeyChecking=accept-new -v root@staging-ipv4.testrun.org id -u ; do sleep 1 ; done
-          ssh -o StrictHostKeyChecking=accept-new -v root@staging-ipv4.testrun.org id -u
-          # download acme & dkim state from ns.testrun.org
-          rsync -e "ssh -o StrictHostKeyChecking=accept-new" -avz root@ns.testrun.org:/tmp/acme-ipv4/acme acme-restore || true
-          rsync -avz root@ns.testrun.org:/tmp/dkimkeys-ipv4/dkimkeys dkimkeys-restore || true
-          # restore acme & dkim state to staging2.testrun.org
-          rsync -avz acme-restore/acme root@staging-ipv4.testrun.org:/var/lib/ || true
-          rsync -avz dkimkeys-restore/dkimkeys root@staging-ipv4.testrun.org:/etc/ || true
-          ssh -o StrictHostKeyChecking=accept-new -v root@staging-ipv4.testrun.org chown root:root -R /var/lib/acme || true
-
-      - name: run deploy-chatmail offline tests 
-        run: pytest --pyargs cmdeploy 
-
-      - name: setup dependencies
-        run: |
-          ssh root@staging-ipv4.testrun.org apt update
-          ssh root@staging-ipv4.testrun.org apt install -y git python3.11-venv python3-dev gcc
-          ssh root@staging-ipv4.testrun.org git clone https://github.com/chatmail/relay
-          ssh root@staging-ipv4.testrun.org "cd relay && git checkout " ${{ github.head_ref }}
-          ssh root@staging-ipv4.testrun.org "cd relay && scripts/initenv.sh"
-
-      - name: initialize config
-        run: |
-          ssh root@staging-ipv4.testrun.org "cd relay && scripts/cmdeploy init staging-ipv4.testrun.org"
-          ssh root@staging-ipv4.testrun.org "sed -i 's#disable_ipv6 = False#disable_ipv6 = True#' relay/chatmail.ini"
-          ssh root@staging-ipv4.testrun.org "sed -i 's/#\s*mtail_address/mtail_address/' relay/chatmail.ini"
-
-      - run: ssh root@staging-ipv4.testrun.org "cd relay && scripts/cmdeploy run --verbose --skip-dns-check --ssh-host localhost"
-
-      - name: set DNS entries
-        run: |
-          ssh root@staging-ipv4.testrun.org chown opendkim:opendkim -R /etc/dkimkeys
-          ssh root@staging-ipv4.testrun.org "cd relay && scripts/cmdeploy dns --zonefile staging-generated.zone --ssh-host localhost"
-          ssh root@staging-ipv4.testrun.org cat relay/staging-generated.zone >> .github/workflows/staging-ipv4.testrun.org-default.zone
-          cat .github/workflows/staging-ipv4.testrun.org-default.zone
-          scp .github/workflows/staging-ipv4.testrun.org-default.zone root@ns.testrun.org:/etc/nsd/staging-ipv4.testrun.org.zone
-          ssh root@ns.testrun.org nsd-checkzone staging-ipv4.testrun.org /etc/nsd/staging-ipv4.testrun.org.zone
-          ssh root@ns.testrun.org systemctl reload nsd
-
-      - name: cmdeploy test
-        run: ssh root@staging-ipv4.testrun.org "cd relay && CHATMAIL_DOMAIN2=ci-chatmail.testrun.org scripts/cmdeploy test --slow --ssh-host localhost"
-
-      - name: cmdeploy dns
-        run: ssh root@staging-ipv4.testrun.org "cd relay && scripts/cmdeploy dns -v --ssh-host localhost"
-

.github/workflows/test-and-deploy.yaml

@@ -1,98 +0,0 @@
-name: deploy on staging2.testrun.org, and run tests
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    paths-ignore:
-      - 'scripts/**'
-      - '**/README.md'
-      - 'CHANGELOG.md'
-      - 'LICENSE'
-
-jobs:
-  deploy:
-    name: deploy on staging2.testrun.org, and run tests
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    environment:
-      name: staging2.testrun.org
-      url: https://staging2.testrun.org/
-    concurrency: staging2.testrun.org
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: prepare SSH
-        run: |
-          mkdir ~/.ssh
-          echo "${{ secrets.STAGING_SSH_KEY }}" >> ~/.ssh/id_ed25519
-          chmod 600 ~/.ssh/id_ed25519
-          ssh-keyscan staging2.testrun.org > ~/.ssh/known_hosts
-          # save previous acme & dkim state
-          rsync -avz root@staging2.testrun.org:/var/lib/acme . || true
-          rsync -avz root@staging2.testrun.org:/etc/dkimkeys . || true
-          # store previous acme & dkim state on ns.testrun.org, if it contains useful certs
-          if [ -f dkimkeys/opendkim.private ]; then rsync -avz -e "ssh -o StrictHostKeyChecking=accept-new" dkimkeys root@ns.testrun.org:/tmp/ || true; fi
-          if [ "$(ls -A acme/certs)" ]; then rsync -avz -e "ssh -o StrictHostKeyChecking=accept-new" acme root@ns.testrun.org:/tmp/ || true; fi
-          # make sure CAA record isn't set
-          scp -o StrictHostKeyChecking=accept-new .github/workflows/staging.testrun.org-default.zone root@ns.testrun.org:/etc/nsd/staging2.testrun.org.zone
-          ssh root@ns.testrun.org sed -i '/CAA/d' /etc/nsd/staging2.testrun.org.zone
-          ssh root@ns.testrun.org nsd-checkzone staging2.testrun.org /etc/nsd/staging2.testrun.org.zone
-          ssh root@ns.testrun.org systemctl reload nsd
-
-      - name: rebuild staging2.testrun.org to have a clean VPS
-        run: |
-            curl -X POST \
-            -H "Authorization: Bearer ${{ secrets.HETZNER_API_TOKEN }}" \
-            -H "Content-Type: application/json" \
-            -d '{"image":"debian-12"}' \
-            "https://api.hetzner.cloud/v1/servers/${{ secrets.STAGING_SERVER_ID }}/actions/rebuild"
-
-      - run: scripts/initenv.sh
-
-      - name: append venv/bin to PATH
-        run: echo venv/bin >>$GITHUB_PATH
-
-      - name: upload TLS cert after rebuilding
-        run: |
-          echo " --- wait until staging2.testrun.org VPS is rebuilt --- "
-          rm ~/.ssh/known_hosts
-          while ! ssh -o ConnectTimeout=180 -o StrictHostKeyChecking=accept-new -v root@staging2.testrun.org id -u ; do sleep 1 ; done
-          ssh -o StrictHostKeyChecking=accept-new -v root@staging2.testrun.org id -u
-          # download acme & dkim state from ns.testrun.org
-          rsync -e "ssh -o StrictHostKeyChecking=accept-new" -avz root@ns.testrun.org:/tmp/acme acme-restore || true
-          rsync -avz root@ns.testrun.org:/tmp/dkimkeys dkimkeys-restore || true
-          # restore acme & dkim state to staging2.testrun.org
-          rsync -avz acme-restore/acme root@staging2.testrun.org:/var/lib/ || true
-          rsync -avz dkimkeys-restore/dkimkeys root@staging2.testrun.org:/etc/ || true
-          ssh -o StrictHostKeyChecking=accept-new -v root@staging2.testrun.org chown root:root -R /var/lib/acme || true
-
-      - name: add hpk42 key to staging server
-        run: ssh root@staging2.testrun.org 'curl -s https://github.com/hpk42.keys >> .ssh/authorized_keys'
-
-      - name: run deploy-chatmail offline tests 
-        run: pytest --pyargs cmdeploy 
-
-      - run: |
-          cmdeploy init staging2.testrun.org
-          sed -i 's/#\s*mtail_address/mtail_address/' chatmail.ini
-
-      - run: cmdeploy run --verbose --skip-dns-check
-
-      - name: set DNS entries
-        run: |
-          ssh -o StrictHostKeyChecking=accept-new root@staging2.testrun.org chown opendkim:opendkim -R /etc/dkimkeys
-          cmdeploy dns --zonefile staging-generated.zone --verbose
-          cat staging-generated.zone >> .github/workflows/staging.testrun.org-default.zone
-          cat .github/workflows/staging.testrun.org-default.zone
-          scp .github/workflows/staging.testrun.org-default.zone root@ns.testrun.org:/etc/nsd/staging2.testrun.org.zone
-          ssh root@ns.testrun.org nsd-checkzone staging2.testrun.org /etc/nsd/staging2.testrun.org.zone
-          ssh root@ns.testrun.org systemctl reload nsd
-
-      - name: cmdeploy test
-        run: CHATMAIL_DOMAIN2=ci-chatmail.testrun.org cmdeploy test --slow
-
-      - name: cmdeploy dns
-        run: cmdeploy dns -v
-

.gitignore

@@ -4,7 +4,7 @@ __pycache__/
 *$py.class
 *.swp
 *qr-*.png
-chatmail.ini
+chatmail*.ini
 
 
 # C extensions
@@ -164,3 +164,9 @@ cython_debug/
 #.idea/
 
 chatmail.zone
+
+# docker
+/data/
+/custom/
+docker-compose.override.yaml
+.env

chatmaild/src/chatmaild/config.py

@@ -60,10 +60,23 @@ class Config:
         self.privacy_pdo = params.get("privacy_pdo")
         self.privacy_supervisor = params.get("privacy_supervisor")
 
-        # TLS certificate management: derived from the domain name.
+        # TLS certificate management.
-        # Domains starting with "_" use self-signed certificates
+        # If tls_external_cert_and_key is set, use externally managed certs.
-        # All other domains use ACME.
+        # Otherwise derived from the domain name:
-        if self.mail_domain.startswith("_"):
+        # - Domains starting with "_" use self-signed certificates
+        # - All other domains use ACME.
+        external = params.get("tls_external_cert_and_key", "").strip()
+
+        if external:
+            parts = external.split()
+            if len(parts) != 2:
+                raise ValueError(
+                    "tls_external_cert_and_key must have two space-separated"
+                    " paths: CERT_PATH KEY_PATH"
+                )
+            self.tls_cert_mode = "external"
+            self.tls_cert_path, self.tls_key_path = parts
+        elif self.mail_domain.startswith("_"):
             self.tls_cert_mode = "self"
             self.tls_cert_path = "/etc/ssl/certs/mailserver.pem"
             self.tls_key_path = "/etc/ssl/private/mailserver.key"

chatmaild/src/chatmaild/fsreport.py

@@ -13,9 +13,20 @@ to show storage summaries only for first 1000 mailboxes
 
     python -m chatmaild.fsreport /path/to/chatmail.ini --maxnum 1000
 
+to write Prometheus textfile for node_exporter
+
+    python -m chatmaild.fsreport --textfile /var/lib/prometheus/node-exporter/
+
+writes to /var/lib/prometheus/node-exporter/fsreport.prom
+
+to also write legacy metrics.py style output (default: /var/www/html/metrics):
+
+    python -m chatmaild.fsreport --textfile /var/lib/prometheus/node-exporter/ --legacy-metrics
+
 """
 
 import os
+import tempfile
 from argparse import ArgumentParser
 from datetime import datetime
 
@@ -48,7 +59,19 @@ class Report:
         self.num_ci_logins = self.num_all_logins = 0
         self.login_buckets = {x: 0 for x in (1, 10, 30, 40, 80, 100, 150)}
 
-        self.message_buckets = {x: 0 for x in (0, 160000, 500000, 2000000)}
+        KiB = 1024
+        MiB = 1024 * KiB
+        self.message_size_thresholds = (
+            0,
+            100 * KiB,
+            MiB // 2,
+            1 * MiB,
+            2 * MiB,
+            5 * MiB,
+            10 * MiB,
+        )
+        self.message_buckets = {x: 0 for x in self.message_size_thresholds}
+        self.message_count_buckets = {x: 0 for x in self.message_size_thresholds}
 
     def process_mailbox_stat(self, mailbox):
         # categorize login times
@@ -68,9 +91,10 @@ class Report:
             for size in self.message_buckets:
                 for msg in mailbox.messages:
                     if msg.size >= size:
-                        if self.mdir and not msg.relpath.startswith(self.mdir):
+                        if self.mdir and f"/{self.mdir}/" not in msg.path:
                             continue
                         self.message_buckets[size] += msg.size
+                        self.message_count_buckets[size] += 1
 
         self.size_messages += sum(entry.size for entry in mailbox.messages)
         self.size_extra += sum(entry.size for entry in mailbox.extrafiles)
@@ -93,9 +117,10 @@ class Report:
 
         pref = f"[{self.mdir}] " if self.mdir else ""
         for minsize, sumsize in self.message_buckets.items():
+            count = self.message_count_buckets[minsize]
             percent = (sumsize / all_messages * 100) if all_messages else 0
             print(
-                f"{pref}larger than {HSize(minsize)}: {HSize(sumsize)} ({percent:.2f}%)"
+                f"{pref}larger than {HSize(minsize)}: {HSize(sumsize)} ({percent:.2f}%), {count} msgs"
             )
 
         user_logins = self.num_all_logins - self.num_ci_logins
@@ -111,6 +136,75 @@ class Report:
         for days, active in self.login_buckets.items():
             print(f"last {days:3} days: {HSize(active)} {p(active)}")
 
+    def _write_atomic(self, filepath, content):
+        """Atomically write content to filepath via tmp+rename."""
+        dirpath = os.path.dirname(os.path.abspath(filepath))
+        fd, tmppath = tempfile.mkstemp(dir=dirpath, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w") as f:
+                f.write(content)
+            os.chmod(tmppath, 0o644)
+            os.rename(tmppath, filepath)
+        except BaseException:
+            try:
+                os.unlink(tmppath)
+            except OSError:
+                pass
+            raise
+
+    def dump_textfile(self, filepath):
+        """Dump metrics in Prometheus exposition format."""
+        lines = []
+
+        lines.append("# HELP chatmail_storage_bytes Mailbox storage in bytes.")
+        lines.append("# TYPE chatmail_storage_bytes gauge")
+        lines.append(f'chatmail_storage_bytes{{kind="messages"}} {self.size_messages}')
+        lines.append(f'chatmail_storage_bytes{{kind="extra"}} {self.size_extra}')
+        total = self.size_extra + self.size_messages
+        lines.append(f'chatmail_storage_bytes{{kind="total"}} {total}')
+
+        lines.append("# HELP chatmail_messages_bytes Sum of msg bytes >= threshold.")
+        lines.append("# TYPE chatmail_messages_bytes gauge")
+        for minsize, sumsize in self.message_buckets.items():
+            lines.append(f'chatmail_messages_bytes{{min_size="{minsize}"}} {sumsize}')
+
+        lines.append("# HELP chatmail_messages_count Number of msgs >= size threshold.")
+        lines.append("# TYPE chatmail_messages_count gauge")
+        for minsize, count in self.message_count_buckets.items():
+            lines.append(f'chatmail_messages_count{{min_size="{minsize}"}} {count}')
+
+        lines.append("# HELP chatmail_accounts Number of accounts.")
+        lines.append("# TYPE chatmail_accounts gauge")
+        user_logins = self.num_all_logins - self.num_ci_logins
+        lines.append(f'chatmail_accounts{{kind="all"}} {self.num_all_logins}')
+        lines.append(f'chatmail_accounts{{kind="ci"}} {self.num_ci_logins}')
+        lines.append(f'chatmail_accounts{{kind="user"}} {user_logins}')
+
+        lines.append(
+            "# HELP chatmail_accounts_active Non-CI accounts active within N days."
+        )
+        lines.append("# TYPE chatmail_accounts_active gauge")
+        for days, active in self.login_buckets.items():
+            lines.append(f'chatmail_accounts_active{{days="{days}"}} {active}')
+
+        self._write_atomic(filepath, "\n".join(lines) + "\n")
+
+    def dump_compat_textfile(self, filepath):
+        """Dump legacy metrics.py style metrics."""
+        user_logins = self.num_all_logins - self.num_ci_logins
+        lines = [
+            "# HELP total number of accounts",
+            "# TYPE accounts gauge",
+            f"accounts {self.num_all_logins}",
+            "# HELP number of CI accounts",
+            "# TYPE ci_accounts gauge",
+            f"ci_accounts {self.num_ci_logins}",
+            "# HELP number of non-CI accounts",
+            "# TYPE nonci_accounts gauge",
+            f"nonci_accounts {user_logins}",
+        ]
+        self._write_atomic(filepath, "\n".join(lines) + "\n")
+
 
 def main(args=None):
     """Report about filesystem storage usage of all mailboxes and messages"""
@@ -127,19 +221,21 @@ def main(args=None):
         "--days",
         default=0,
         action="store",
-        help="assume date to be days older than now",
+        help="assume date to be DAYS older than now",
     )
     parser.add_argument(
         "--min-login-age",
         default=0,
+        metavar="DAYS",
         dest="min_login_age",
         action="store",
-        help="only sum up message size if last login is at least min-login-age days old",
+        help="only sum up message size if last login is at least DAYS days old",
     )
     parser.add_argument(
         "--mdir",
+        metavar="{cur,new,tmp}",
         action="store",
-        help="only consider 'cur' or 'new' or 'tmp' messages for summary",
+        help="only consider messages in specified Maildir subdirectory for summary",
     )
 
     parser.add_argument(
@@ -148,6 +244,21 @@ def main(args=None):
         action="store",
         help="maximum number of mailboxes to iterate on",
     )
+    parser.add_argument(
+        "--textfile",
+        metavar="PATH",
+        default=None,
+        help="write Prometheus textfile to PATH (directory or file); "
+        "if PATH is a directory, writes 'fsreport.prom' inside it",
+    )
+    parser.add_argument(
+        "--legacy-metrics",
+        metavar="FILENAME",
+        nargs="?",
+        const="/var/www/html/metrics",
+        default=None,
+        help="write legacy metrics.py textfile (default: /var/www/html/metrics)",
+    )
 
     args = parser.parse_args(args)
 
@@ -161,7 +272,15 @@ def main(args=None):
     rep = Report(now=now, min_login_age=int(args.min_login_age), mdir=args.mdir)
     for mbox in iter_mailboxes(str(config.mailboxes_dir), maxnum=maxnum):
         rep.process_mailbox_stat(mbox)
-    rep.dump_summary()
+    if args.textfile:
+        path = args.textfile
+        if os.path.isdir(path):
+            path = os.path.join(path, "fsreport.prom")
+        rep.dump_textfile(path)
+    if args.legacy_metrics:
+        rep.dump_compat_textfile(args.legacy_metrics)
+    if not args.textfile and not args.legacy_metrics:
+        rep.dump_summary()
 
 
 if __name__ == "__main__":

chatmaild/src/chatmaild/ini/chatmail.ini.f

@@ -48,6 +48,13 @@ passthrough_senders =
 # (space-separated, item may start with "@" to whitelist whole recipient domains)
 passthrough_recipients =
 
+# Use externally managed TLS certificates instead of built-in acmetool.
+# Paths refer to files on the deployment server (not the build machine).
+# Both files must already exist before running cmdeploy.
+# Certificate renewal is your responsibility; changed files are
+# picked up automatically by all relay services.
+# tls_external_cert_and_key = /path/to/fullchain.pem /path/to/privkey.pem
+
 # path to www directory - documented here: https://chatmail.at/doc/relay/getting_started.html#custom-web-pages
 #www_folder = www
 

chatmaild/src/chatmaild/tests/test_config.py

@@ -87,3 +87,37 @@ def test_config_tls_self(make_config):
     assert config.tls_cert_mode == "self"
     assert config.tls_cert_path == "/etc/ssl/certs/mailserver.pem"
     assert config.tls_key_path == "/etc/ssl/private/mailserver.key"
+
+
+def test_config_tls_external(make_config):
+    config = make_config(
+        "chat.example.org",
+        {
+            "tls_external_cert_and_key": "/custom/fullchain.pem /custom/privkey.pem",
+        },
+    )
+    assert config.tls_cert_mode == "external"
+    assert config.tls_cert_path == "/custom/fullchain.pem"
+    assert config.tls_key_path == "/custom/privkey.pem"
+
+
+def test_config_tls_external_overrides_underscore(make_config):
+    config = make_config(
+        "_test.example.org",
+        {
+            "tls_external_cert_and_key": "/certs/fullchain.pem /certs/privkey.pem",
+        },
+    )
+    assert config.tls_cert_mode == "external"
+    assert config.tls_cert_path == "/certs/fullchain.pem"
+    assert config.tls_key_path == "/certs/privkey.pem"
+
+
+def test_config_tls_external_bad_format(make_config):
+    with pytest.raises(ValueError, match="two space-separated"):
+        make_config(
+            "chat.example.org",
+            {
+                "tls_external_cert_and_key": "/only/one/path.pem",
+            },
+        )

chatmaild/src/chatmaild/tests/test_filtermail_blackbox.py

@@ -47,6 +47,8 @@ def test_one_mail(
     make_config, make_popen, smtpserver, maildata, filtermail_mode, monkeypatch
 ):
     monkeypatch.setenv("PYTHONUNBUFFERED", "1")
+    # DKIM is tested by cmdeploy tests.
+    monkeypatch.setenv("FILTERMAIL_SKIP_DKIM", "1")
     smtp_inject_port = 20025
     if filtermail_mode == "outgoing":
         settings = dict(
@@ -64,6 +66,10 @@ def test_one_mail(
 
     popen = make_popen(["filtermail", path, filtermail_mode])
     line = popen.stderr.readline().strip()
+
+    # skip a warning that FILTERMAIL_SKIP_DKIM shouldn't be used in prod
+    if b"DKIM verification DISABLED!" in line:
+        line = popen.stderr.readline().strip()
     if b"loop" not in line:
         print(line.decode("ascii"), file=sys.stderr)
         pytest.fail("starting filtermail failed")

cmdeploy/pyproject.toml

@@ -20,6 +20,7 @@ dependencies = [
   "pytest-xdist", 
   "execnet",
   "imap_tools",
+  "deltachat-rpc-client",
 ]
 
 [project.scripts]

cmdeploy/src/cmdeploy/acmetool/acmetool-redirector.service

@@ -3,7 +3,7 @@ Description=acmetool HTTP redirector
 
 [Service]
 Type=notify
-ExecStart=/usr/bin/acmetool redirector --service.uid=daemon
+ExecStart=/usr/bin/acmetool redirector --service.uid=daemon --bind=127.0.0.1:402
 Restart=always
 RestartSec=30
 

cmdeploy/src/cmdeploy/basedeploy.py

@@ -5,6 +5,11 @@ import os
 from pyinfra.operations import files, server, systemd
 
 
+def has_systemd():
+    """Returns False during Docker image builds or any other non-systemd environment."""
+    return os.path.isdir("/run/systemd/system")
+
+
 def get_resource(arg, pkg=__package__):
     return importlib.resources.files(pkg).joinpath(arg)
 

cmdeploy/src/cmdeploy/cmdeploy.py

@@ -5,7 +5,6 @@ along with command line option and subcommand parsing.
 
 import argparse
 import importlib.resources
-import importlib.util
 import os
 import pathlib
 import shutil
@@ -109,7 +108,7 @@ def run_cmd(args, out):
     pyinf = "pyinfra --dry" if args.dry_run else "pyinfra"
 
     cmd = f"{pyinf} --ssh-user root {ssh_host} {deploy_path} -y"
-    if ssh_host in ["localhost", "@docker"]:
+    if ssh_host == "localhost":
         cmd = f"{pyinf} @local {deploy_path} -y"
 
     if version.parse(pyinfra.__version__) < version.parse("3"):
@@ -211,14 +210,8 @@ def test_cmd_options(parser):
 
 
 def test_cmd(args, out):
-    """Run local and online tests for chatmail deployment.
+    """Run local and online tests for chatmail deployment."""
 
-    This will automatically pip-install 'deltachat' if it's not available.
-    """
-
-    x = importlib.util.find_spec("deltachat")
-    if x is None:
-        out.check_call(f"{sys.executable} -m pip install deltachat")
     env = os.environ.copy()
     if args.ssh_host:
         env["CHATMAIL_SSH"] = args.ssh_host
@@ -326,7 +319,7 @@ def add_ssh_host_option(parser):
     parser.add_argument(
         "--ssh-host",
         dest="ssh_host",
-        help="Run commands on 'localhost', via '@docker', or on a specific SSH host "
+        help="Run commands on 'localhost' or on a specific SSH host "
         "instead of chatmail.ini's mail_domain.",
     )
 
@@ -336,7 +329,7 @@ def add_config_option(parser):
         "--config",
         dest="inipath",
         action="store",
-        default=Path("chatmail.ini"),
+        default=Path(os.environ.get("CHATMAIL_INI", "chatmail.ini")),
         type=Path,
         help="path to the chatmail.ini file",
     )
@@ -388,9 +381,7 @@ def get_parser():
 
 def get_sshexec(ssh_host: str, verbose=True):
     if ssh_host in ["localhost", "@local"]:
-        return LocalExec(verbose, docker=False)
+        return LocalExec(verbose)
-    elif ssh_host == "@docker":
-        return LocalExec(verbose, docker=True)
     if verbose:
         print(f"[ssh] login to {ssh_host}")
     return SSHExec(ssh_host, verbose=verbose)

cmdeploy/src/cmdeploy/deployers.py

@@ -2,6 +2,7 @@
 Chat Mail pyinfra deploy.
 """
 
+import os
 import shutil
 import subprocess
 import sys
@@ -10,8 +11,8 @@ from pathlib import Path
 
 from chatmaild.config import read_config
 from pyinfra import facts, host, logger
-from pyinfra.facts import hardware
 from pyinfra.api import FactBase
+from pyinfra.facts import hardware
 from pyinfra.facts.files import Sha256File
 from pyinfra.facts.systemd import SystemdEnabled
 from pyinfra.operations import apt, files, pip, server, systemd
@@ -19,20 +20,22 @@ from pyinfra.operations import apt, files, pip, server, systemd
 from cmdeploy.cmdeploy import Out
 
 from .acmetool import AcmetoolDeployer
-from .selfsigned.deployer import SelfSignedTlsDeployer
 from .basedeploy import (
     Deployer,
     Deployment,
     activate_remote_units,
     configure_remote_units,
     get_resource,
+    has_systemd,
 )
 from .dovecot.deployer import DovecotDeployer
+from .external.deployer import ExternalTlsDeployer
 from .filtermail.deployer import FiltermailDeployer
 from .mtail.deployer import MtailDeployer
 from .nginx.deployer import NginxDeployer
 from .opendkim.deployer import OpendkimDeployer
 from .postfix.deployer import PostfixDeployer
+from .selfsigned.deployer import SelfSignedTlsDeployer
 from .www import build_webpages, find_merge_conflict, get_paths
 
 
@@ -66,6 +69,8 @@ def _build_chatmaild(dist_dir) -> None:
 
 
 def remove_legacy_artifacts():
+    if not has_systemd():
+        return
     # disable legacy doveauth-dictproxy.service
     if host.get_fact(SystemdEnabled).get("doveauth-dictproxy.service"):
         systemd.service(
@@ -300,7 +305,7 @@ class LegacyRemoveDeployer(Deployer):
             present=False,
         )
         # remove echobot if it is still running
-        if host.get_fact(SystemdEnabled).get("echobot.service"):
+        if has_systemd() and host.get_fact(SystemdEnabled).get("echobot.service"):
             systemd.service(
                 name="Disable echobot.service",
                 service="echobot.service",
@@ -536,6 +541,20 @@ class GithashDeployer(Deployer):
         )
 
 
+def get_tls_deployer(config, mail_domain):
+    """Select the appropriate TLS deployer based on config."""
+    tls_domains = [mail_domain, f"mta-sts.{mail_domain}", f"www.{mail_domain}"]
+
+    if config.tls_cert_mode == "acme":
+        return AcmetoolDeployer(config.acme_email, tls_domains)
+    elif config.tls_cert_mode == "self":
+        return SelfSignedTlsDeployer(mail_domain)
+    elif config.tls_cert_mode == "external":
+        return ExternalTlsDeployer(config.tls_cert_path, config.tls_key_path)
+    else:
+        raise ValueError(f"Unknown tls_cert_mode: {config.tls_cert_mode}")
+
+
 def deploy_chatmail(config_path: Path, disable_mail: bool, website_only: bool) -> None:
     """Deploy a chat-mail instance.
 
@@ -567,44 +586,44 @@ def deploy_chatmail(config_path: Path, disable_mail: bool, website_only: bool) -
             Out().red(f"Deploy failed: mtail_address {config.mtail_address} is not available (VPN up?).\n")
             exit(1)
 
-    port_services = [
+    if not os.environ.get("CHATMAIL_NOPORTCHECK"):
-        (["master", "smtpd"], 25),
+        port_services = [
-        ("unbound", 53),
+            (["master", "smtpd"], 25),
-    ]
+            ("unbound", 53),
-    if config.tls_cert_mode == "acme":
+        ]
-        port_services.append(("acmetool", 80))
+        if config.tls_cert_mode == "acme":
-    port_services += [
+            port_services.append(("acmetool", 402))
-        (["imap-login", "dovecot"], 143),
+        port_services += [
-        ("nginx", 443),
+            (["imap-login", "dovecot"], 143),
-        (["master", "smtpd"], 465),
+            # acmetool previously listened on port 80,
-        (["master", "smtpd"], 587),
+            # so don't complain during upgrade that moved it to port 402
-        (["imap-login", "dovecot"], 993),
+            # and gave the port to nginx.
-        ("iroh-relay", 3340),
+            (["acmetool", "nginx"], 80),
-        ("mtail", 3903),
+            ("nginx", 443),
-        ("stats", 3904),
+            (["master", "smtpd"], 465),
-        ("nginx", 8443),
+            (["master", "smtpd"], 587),
-        (["master", "smtpd"], config.postfix_reinject_port),
+            (["imap-login", "dovecot"], 993),
-        (["master", "smtpd"], config.postfix_reinject_port_incoming),
+            ("iroh-relay", 3340),
-        ("filtermail", config.filtermail_smtp_port),
+            ("mtail", 3903),
-        ("filtermail", config.filtermail_smtp_port_incoming),
+            ("stats", 3904),
-    ]
+            ("nginx", 8443),
-    for service, port in port_services:
+            (["master", "smtpd"], config.postfix_reinject_port),
-        print(f"Checking if port {port} is available for {service}...")
+            (["master", "smtpd"], config.postfix_reinject_port_incoming),
-        running_service = host.get_fact(Port, port=port)
+            ("filtermail", config.filtermail_smtp_port),
-        services = [service] if isinstance(service, str) else service
+            ("filtermail", config.filtermail_smtp_port_incoming),
-        if running_service:
+        ]
-            if running_service not in services:
+        for service, port in port_services:
-                Out().red(
+            print(f"Checking if port {port} is available for {service}...")
-                    f"Deploy failed: port {port} is occupied by: {running_service}"
+            running_service = host.get_fact(Port, port=port)
-                )
+            services = [service] if isinstance(service, str) else service
-                exit(1)
+            if running_service:
+                if running_service not in services:
+                    Out().red(
+                        f"Deploy failed: port {port} is occupied by: {running_service}"
+                    )
+                    exit(1)
 
-    tls_domains = [mail_domain, f"mta-sts.{mail_domain}", f"www.{mail_domain}"]
+    tls_deployer = get_tls_deployer(config, mail_domain)
-
-    if config.tls_cert_mode == "acme":
-        tls_deployer = AcmetoolDeployer(config.acme_email, tls_domains)
-    else:
-        tls_deployer = SelfSignedTlsDeployer(mail_domain)
 
     all_deployers = [
         ChatmailDeployer(mail_domain),

cmdeploy/src/cmdeploy/dovecot/deployer.py

@@ -1,3 +1,6 @@
+import os
+import urllib.request
+
 from chatmaild.config import Config
 from pyinfra import host
 from pyinfra.facts.server import Arch, Sysctl
@@ -9,6 +12,7 @@ from cmdeploy.basedeploy import (
     activate_remote_units,
     configure_remote_units,
     get_resource,
+    has_systemd,
 )
 
 
@@ -22,10 +26,11 @@ class DovecotDeployer(Deployer):
 
     def install(self):
         arch = host.get_fact(Arch)
-        if not host.get_fact(SystemdEnabled).get("dovecot.service"):
+        if has_systemd() and "dovecot.service" in host.get_fact(SystemdEnabled):
-            _install_dovecot_package("core", arch)
+            return  # already installed and running
-            _install_dovecot_package("imapd", arch)
+        _install_dovecot_package("core", arch)
-            _install_dovecot_package("lmtpd", arch)
+        _install_dovecot_package("imapd", arch)
+        _install_dovecot_package("lmtpd", arch)
 
     def configure(self):
         configure_remote_units(self.config.mail_domain, self.units)
@@ -47,10 +52,21 @@ class DovecotDeployer(Deployer):
         self.need_restart = False
 
 
+def _pick_url(primary, fallback):
+    try:
+        req = urllib.request.Request(primary, method="HEAD")
+        urllib.request.urlopen(req, timeout=10)
+        return primary
+    except Exception:
+        return fallback
+
+
 def _install_dovecot_package(package: str, arch: str):
     arch = "amd64" if arch == "x86_64" else arch
     arch = "arm64" if arch == "aarch64" else arch
-    url = f"https://download.delta.chat/dovecot/dovecot-{package}_2.3.21%2Bdfsg1-3_{arch}.deb"
+    primary_url = f"https://download.delta.chat/dovecot/dovecot-{package}_2.3.21%2Bdfsg1-3_{arch}.deb"
+    fallback_url = f"https://github.com/chatmail/dovecot/releases/download/upstream%2F2.3.21%2Bdfsg1/dovecot-{package}_2.3.21%2Bdfsg1-3_{arch}.deb"
+    url = _pick_url(primary_url, fallback_url)
     deb_filename = "/root/" + url.split("/")[-1]
 
     match (package, arch):
@@ -116,18 +132,19 @@ def _configure_dovecot(config: Config, debug: bool = False) -> (bool, bool):
 
     # as per https://doc.dovecot.org/2.3/configuration_manual/os/
     # it is recommended to set the following inotify limits
-    for name in ("max_user_instances", "max_user_watches"):
+    if not os.environ.get("CHATMAIL_NOSYSCTL"):
-        key = f"fs.inotify.{name}"
+        for name in ("max_user_instances", "max_user_watches"):
-        if host.get_fact(Sysctl)[key] > 65535:
+            key = f"fs.inotify.{name}"
-            # Skip updating limits if already sufficient
+            if host.get_fact(Sysctl)[key] > 65535:
-            # (enables running in incus containers where sysctl readonly)
+                # Skip updating limits if already sufficient
-            continue
+                # (enables running in incus containers where sysctl readonly)
-        server.sysctl(
+                continue
-            name=f"Change {key}",
+            server.sysctl(
-            key=key,
+                name=f"Change {key}",
-            value=65535,
+                key=key,
-            persist=True,
+                value=65535,
-        )
+                persist=True,
+            )
 
     timezone_env = files.line(
         name="Set TZ environment variable",

cmdeploy/src/cmdeploy/external/deployer.py

@@ -0,0 +1,67 @@
+import io
+
+from pyinfra import host
+from pyinfra.facts.files import File
+from pyinfra.operations import files, systemd
+
+from cmdeploy.basedeploy import Deployer, get_resource
+
+
+class ExternalTlsDeployer(Deployer):
+    """Expects TLS certificates to be managed on the server.
+
+    Validates that the configured certificate and key files
+    exist on the remote host.  Installs a systemd path unit
+    that watches the certificate file and automatically
+    restarts/reloads affected services when it changes.
+    """
+
+    def __init__(self, cert_path, key_path):
+        self.cert_path = cert_path
+        self.key_path = key_path
+
+    def configure(self):
+        # Verify cert and key exist on the remote host using pyinfra facts.
+        for path in (self.cert_path, self.key_path):
+            info = host.get_fact(File, path=path)
+            if info is None:
+                raise Exception(f"External TLS file not found on server: {path}")
+
+        # Deploy the .path unit (templated with the cert path).
+        # pkg=__package__ is required here because the resource files
+        # live in cmdeploy.external, not the default cmdeploy package.
+        source = get_resource("tls-cert-reload.path.f", pkg=__package__)
+        content = source.read_text().format(cert_path=self.cert_path).encode()
+
+        path_unit = files.put(
+            name="Upload tls-cert-reload.path",
+            src=io.BytesIO(content),
+            dest="/etc/systemd/system/tls-cert-reload.path",
+            user="root",
+            group="root",
+            mode="644",
+        )
+
+        service_unit = files.put(
+            name="Upload tls-cert-reload.service",
+            src=get_resource("tls-cert-reload.service", pkg=__package__),
+            dest="/etc/systemd/system/tls-cert-reload.service",
+            user="root",
+            group="root",
+            mode="644",
+        )
+
+        if path_unit.changed or service_unit.changed:
+            self.need_restart = True
+
+    def activate(self):
+        systemd.service(
+            name="Enable tls-cert-reload path watcher",
+            service="tls-cert-reload.path",
+            running=True,
+            enabled=True,
+            restarted=self.need_restart,
+            daemon_reload=self.need_restart,
+        )
+        # No explicit reload needed here: dovecot/nginx read the cert
+        # on startup, and the .path watcher handles live changes.

cmdeploy/src/cmdeploy/external/tls-cert-reload.path.f

@@ -0,0 +1,15 @@
+# Watch the TLS certificate file for changes.
+# When the cert is updated (e.g. renewed by an external process),
+# this triggers tls-cert-reload.service to reload the affected services.
+#
+# NOTE: changes to the certificates are not detected if they cross bind-mount boundaries. 
+# After cert renewal, you must then trigger the reload explicitly:
+#   systemctl start tls-cert-reload.service
+[Unit]
+Description=Watch TLS certificate for changes
+
+[Path]
+PathChanged={cert_path}
+
+[Install]
+WantedBy=multi-user.target

cmdeploy/src/cmdeploy/external/tls-cert-reload.service

@@ -0,0 +1,15 @@
+# Reload services that cache the TLS certificate.
+#
+# dovecot: caches the cert at startup; reload re-reads SSL certs
+#          without dropping existing connections.
+# nginx:   caches the cert at startup; reload gracefully picks up
+#          the new cert for new connections.
+# postfix: reads the cert fresh on each TLS handshake,
+#          does NOT need a reload/restart.
+[Unit]
+Description=Reload TLS services after certificate change
+
+[Service]
+Type=oneshot
+ExecStart=/bin/systemctl try-reload-or-restart dovecot
+ExecStart=/bin/systemctl try-reload-or-restart nginx

cmdeploy/src/cmdeploy/filtermail/deployer.py

@@ -14,10 +14,10 @@ class FiltermailDeployer(Deployer):
 
     def install(self):
         arch = host.get_fact(facts.server.Arch)
-        url = f"https://github.com/chatmail/filtermail/releases/download/v0.3.0/filtermail-{arch}"
+        url = f"https://github.com/chatmail/filtermail/releases/download/v0.5.2/filtermail-{arch}"
         sha256sum = {
-            "x86_64": "f14a31323ae2dad3b59d3fdafcde507521da2f951a9478cd1f2fe2b4463df71d",
+            "x86_64": "ce24ca0075aa445510291d775fb3aea8f4411818c7b885ae51a0fe18c5f789ce",
-            "aarch64": "933770d75046c4fd7084ce8d43f905f8748333426ad839154f0fc654755ef09f",
+            "aarch64": "c5d783eefa5332db3d97a0e6a23917d72849e3eb45da3d16ce908a9b4e5a797d",
         }[arch]
         self.need_restart |= files.download(
             name="Download filtermail",

cmdeploy/src/cmdeploy/nginx/nginx.conf.j2

@@ -84,7 +84,7 @@ http {
 		}
 
 		location /new {
-{% if config.tls_cert_mode == "acme" %}
+{% if config.tls_cert_mode != "self" %}
 			if ($request_method = GET) {
 				# Redirect to Delta Chat,
 				# which will in turn do a POST request.
@@ -106,7 +106,7 @@ http {
 		#
 		# Redirects are only for browsers.
 		location /cgi-bin/newemail.py {
-{% if config.tls_cert_mode == "acme" %}
+{% if config.tls_cert_mode != "self" %}
 			if ($request_method = GET) {
 				return 301 dcaccount:https://{{ config.mail_domain }}/new;
 			}
@@ -145,4 +145,25 @@ http {
 		return 301 $scheme://{{ config.mail_domain }}$request_uri;
 		access_log syslog:server=unix:/dev/log,facility=local7;
 	}
+
+	server {
+		listen 80;
+		{% if not disable_ipv6 %}
+		listen [::]:80;
+		{% endif %}
+
+		{% if config.tls_cert_mode == "acme" %}
+		location /.well-known/acme-challenge/ {
+			proxy_pass http://acmetool;
+		}
+		{% endif %}
+
+		return 301 https://$host$request_uri;
+	}
+
+	{% if config.tls_cert_mode == "acme" %}
+	upstream acmetool {
+		server 127.0.0.1:402;
+	}
+	{% endif %}
 }

cmdeploy/src/cmdeploy/opendkim/deployer.py

@@ -37,21 +37,15 @@ class OpendkimDeployer(Deployer):
         )
         need_restart |= main_config.changed
 
-        screen_script = files.put(
+        screen_script = files.file(
-            src=get_resource("opendkim/screen.lua"),
+            path="/etc/opendkim/screen.lua",
-            dest="/etc/opendkim/screen.lua",
+            present=False,
-            user="root",
-            group="root",
-            mode="644",
         )
         need_restart |= screen_script.changed
 
-        final_script = files.put(
+        final_script = files.file(
-            src=get_resource("opendkim/final.lua"),
+            path="/etc/opendkim/final.lua",
-            dest="/etc/opendkim/final.lua",
+            present=False,
-            user="root",
-            group="root",
-            mode="644",
         )
         need_restart |= final_script.changed
 
@@ -109,6 +103,13 @@ class OpendkimDeployer(Deployer):
         )
         need_restart |= service_file.changed
 
+        files.file(
+            name="chown opendkim: /etc/dkimkeys/opendkim.private",
+            path="/etc/dkimkeys/opendkim.private",
+            user="opendkim",
+            group="opendkim",
+        )
+
         self.need_restart = need_restart
 
     def activate(self):

cmdeploy/src/cmdeploy/opendkim/final.lua

@@ -1,42 +0,0 @@
-mtaname = odkim.get_mtasymbol(ctx, "{daemon_name}")
-if mtaname == "ORIGINATING" then
-	-- Outgoing message will be signed,
-	-- no need to look for signatures.
-	return nil
-end
-
-nsigs = odkim.get_sigcount(ctx)
-if nsigs == nil then
-	return nil
-end
-
-local valid = false
-local error_msg = "No valid DKIM signature found."
-for i = 1, nsigs do
-	sig = odkim.get_sighandle(ctx, i - 1)
-	sigres = odkim.sig_result(sig)
-
-	-- All signatures that do not correspond to From: 
-	-- were ignored in screen.lua and return sigres -1.
-	-- 
-	-- Any valid signature that was not ignored like this
-	-- means the message is acceptable.
-	if sigres == 0 then
-		valid = true
-    else
-        error_msg = "DKIM signature is invalid, error code " .. tostring(sigres) .. ", search https://github.com/trusteddomainproject/OpenDKIM/blob/master/libopendkim/dkim.h#L108"
-	end
-end
-
-if valid then
-	-- Strip all DKIM-Signature headers after successful validation
-	-- Delete in reverse order to avoid index shifting.
-	for i = nsigs, 1, -1 do
-		odkim.del_header(ctx, "DKIM-Signature", i)
-	end
-else
-	odkim.set_reply(ctx, "554", "5.7.1", error_msg)
-	odkim.set_result(ctx, SMFIS_REJECT)
-end
-
-return nil

cmdeploy/src/cmdeploy/opendkim/opendkim.conf

@@ -45,12 +45,6 @@ SignHeaders *,+autocrypt,+content-type
 # Default is empty.
 OversignHeaders from,reply-to,subject,date,to,cc,resent-date,resent-from,resent-sender,resent-to,resent-cc,in-reply-to,references,list-id,list-help,list-unsubscribe,list-subscribe,list-post,list-owner,list-archive,autocrypt
 
-# Script to ignore signatures that do not correspond to the From: domain.
-ScreenPolicyScript /etc/opendkim/screen.lua
-
-# Script to reject mails without a valid DKIM signature.
-FinalPolicyScript /etc/opendkim/final.lua
-
 # In Debian, opendkim runs as user "opendkim". A umask of 007 is required when
 # using a local socket with MTAs that access the socket as a non-privileged
 # user (for example, Postfix). You may need to add user "postfix" to group

cmdeploy/src/cmdeploy/opendkim/screen.lua

@@ -1,21 +0,0 @@
--- Ignore signatures that do not correspond to the From: domain.
-
-from_domain = odkim.get_fromdomain(ctx)
-if from_domain == nil then
-	return nil
-end
-
-n = odkim.get_sigcount(ctx)
-if n == nil then
-	return nil
-end
-
-for i = 1, n do
-	sig = odkim.get_sighandle(ctx, i - 1)
-	sig_domain = odkim.sig_getdomain(sig)
-	if from_domain ~= sig_domain then
-		odkim.sig_ignore(sig)
-	end
-end
-
-return nil

cmdeploy/src/cmdeploy/postfix/master.cf.j2

@@ -86,7 +86,6 @@ filter    unix -        n       n       -       -       lmtp
 # Local SMTP server for reinjecting incoming filtered mail 
 127.0.0.1:{{ config.postfix_reinject_port_incoming }} inet  n       -       n       -       100      smtpd
   -o syslog_name=postfix/reinject_incoming
-  -o smtpd_milters=unix:opendkim/opendkim.sock
 
 # Cleanup `Received` headers for authenticated mail
 # to avoid leaking client IP.

cmdeploy/src/cmdeploy/selfsigned/deployer.py

@@ -1,8 +1,29 @@
-from pyinfra.operations import apt, files, server
+import shlex
+
+from pyinfra.operations import apt, server
 
 from cmdeploy.basedeploy import Deployer
 
 
+def openssl_selfsigned_args(domain, cert_path, key_path, days=36500):
+    """Return the openssl argument list for a self-signed certificate.
+
+    The certificate uses an EC P-256 key with SAN entries for *domain*,
+    ``www.<domain>`` and ``mta-sts.<domain>``.
+    """
+    return [
+        "openssl", "req", "-x509",
+        "-newkey", "ec", "-pkeyopt", "ec_paramgen_curve:P-256",
+        "-noenc", "-days", str(days),
+        "-keyout", str(key_path),
+        "-out", str(cert_path),
+        "-subj", f"/CN={domain}",
+        "-addext", "extendedKeyUsage=serverAuth,clientAuth",
+        "-addext",
+        f"subjectAltName=DNS:{domain},DNS:www.{domain},DNS:mta-sts.{domain}",
+    ]
+
+
 class SelfSignedTlsDeployer(Deployer):
     """Generates a self-signed TLS certificate for all chatmail endpoints."""
 
@@ -18,18 +39,13 @@ class SelfSignedTlsDeployer(Deployer):
         )
 
     def configure(self):
+        args = openssl_selfsigned_args(
+            self.mail_domain, self.cert_path, self.key_path,
+        )
+        cmd = shlex.join(args)
         server.shell(
             name="Generate self-signed TLS certificate if not present",
-            commands=[
+            commands=[f"[ -f {self.cert_path} ] || {cmd}"],
-                f"[ -f {self.cert_path} ] || openssl req -x509"
-                f" -newkey ec -pkeyopt ec_paramgen_curve:P-256"
-                f" -noenc -days 36500"
-                f" -keyout {self.key_path}"
-                f" -out {self.cert_path}"
-                f' -subj "/CN={self.mail_domain}"'
-                f' -addext "extendedKeyUsage=serverAuth,clientAuth"'
-                f' -addext "subjectAltName=DNS:{self.mail_domain},DNS:www.{self.mail_domain},DNS:mta-sts.{self.mail_domain}"',
-            ],
         )
 
     def activate(self):

cmdeploy/src/cmdeploy/sshexec.py

@@ -50,6 +50,9 @@ class SSHExec:
     FuncError = FuncError
 
     def __init__(self, host, verbose=False, python="python3", timeout=60):
+        docker_container = os.environ.get("CHATMAIL_DOCKER")
+        if docker_container:
+            python = f"docker exec -i {docker_container} python3"
         self.gateway = execnet.makegateway(f"ssh=root@{host}//python={python}")
         self._remote_cmdloop_channel = bootstrap_remote(self.gateway, remote)
         self.timeout = timeout
@@ -87,9 +90,8 @@ class SSHExec:
 class LocalExec:
     FuncError = FuncError
 
-    def __init__(self, verbose=False, docker=False):
+    def __init__(self, verbose=False):
         self.verbose = verbose
-        self.docker = docker
 
     def __call__(self, call, kwargs=None, log_callback=None):
         if kwargs is None:
@@ -101,10 +103,6 @@ class LocalExec:
         if not title:
             title = call.__name__
         where = "locally"
-        if self.docker:
-            if call == remote.rdns.perform_initial_checks:
-                kwargs["pre_command"] = "docker exec chatmail "
-                where = "in docker"
         if self.verbose:
             print_stderr(f"Running {where}: {title}(**{kwargs})")
             return self(call, kwargs, log_callback=print_stderr)

cmdeploy/src/cmdeploy/tests/online/benchmark.py

@@ -1,3 +1,4 @@
+import time
 def test_tls_imap(benchmark, imap):
     def imap_connect():
         imap.connect()
@@ -41,9 +42,9 @@ class TestDC:
 
         def dc_ping_pong():
             chat.send_text("ping")
-            msg = ac2._evtracker.wait_next_incoming_message()
+            msg = ac2.wait_for_incoming_msg()
-            msg.chat.send_text("pong")
+            msg.get_snapshot().chat.send_text("pong")
-            ac1._evtracker.wait_next_incoming_message()
+            ac1.wait_for_incoming_msg()
 
         benchmark(dc_ping_pong, 5)
 
@@ -55,6 +56,6 @@ class TestDC:
             for i in range(10):
                 chat.send_text(f"hello {i}")
             for i in range(10):
-                ac2._evtracker.wait_next_incoming_message()
+                ac2.wait_for_incoming_msg()
 
-        benchmark(dc_send_10_receive_10, 5)
+        benchmark(dc_send_10_receive_10, 5, cooldown="auto")

cmdeploy/src/cmdeploy/tests/online/test_1_basic.py

@@ -86,10 +86,8 @@ def test_remote(remote, imap_or_smtp):
 
 
 def test_use_two_chatmailservers(cmfactory, maildomain2):
-    ac1 = cmfactory.new_online_configuring_account(cache=False)
+    ac1 = cmfactory.get_online_account()
-    cmfactory.switch_maildomain(maildomain2)
+    ac2 = cmfactory.get_online_account(domain=maildomain2)
-    ac2 = cmfactory.new_online_configuring_account(cache=False)
-    cmfactory.bring_accounts_online()
     cmfactory.get_accepted_chat(ac1, ac2)
     domain1 = ac1.get_config("addr").split("@")[1]
     domain2 = ac2.get_config("addr").split("@")[1]
@@ -149,7 +147,7 @@ def test_reject_missing_dkim(cmsetup, maildata, from_addr):
     conn.starttls()
 
     with conn as s:
-        with pytest.raises(smtplib.SMTPDataError, match="No valid DKIM signature"):
+        with pytest.raises(smtplib.SMTPDataError, match="No DKIM signature found"):
             s.sendmail(from_addr=from_addr, to_addrs=recipient.addr, msg=msg)
 
 

cmdeploy/src/cmdeploy/tests/online/test_2_deltachat.py

@@ -27,6 +27,7 @@ class TestMetadataTokens:
 
     def test_set_get_metadata(self, imap_mailbox):
         "set and get metadata token for an account"
+        time.sleep(5)  # make sure Metadata service had a chance to restart
         client = imap_mailbox.client
         client.send(b'a01 SETMETADATA INBOX (/private/devicetoken "1111" )\n')
         res = client.readline()
@@ -62,8 +63,8 @@ class TestEndToEndDeltaChat:
         chat.send_text("message0")
 
         lp.sec("wait for ac2 to receive message")
-        msg2 = ac2._evtracker.wait_next_incoming_message()
+        msg2 = ac2.wait_for_incoming_msg()
-        assert msg2.text == "message0"
+        assert msg2.get_snapshot().text == "message0"
 
     def test_exceed_quota(
         self, cmfactory, lp, tmpdir, remote, chatmail_config, sshdomain
@@ -98,38 +99,34 @@ class TestEndToEndDeltaChat:
 
         lp.sec("ac2: check quota is triggered")
 
-        starting = True
+        def send_hello():
-        for line in remote.iter_output("journalctl -n0 -f -u dovecot"):
+            chat.send_text("hello")
-            if starting:
+
-                chat.send_text("hello")
+        for line in remote.iter_output(
-                starting = False
+            "journalctl -n1 -f -u dovecot", ready=send_hello
+        ):
             if user not in line:
-                # print(line)
                 continue
             if "quota exceeded" in line:
                 return
 
     def test_securejoin(self, cmfactory, lp, maildomain2):
-        ac1 = cmfactory.new_online_configuring_account(cache=False)
+        ac1 = cmfactory.get_online_account()
-        cmfactory.switch_maildomain(maildomain2)
+        ac2 = cmfactory.get_online_account(domain=maildomain2)
-        ac2 = cmfactory.new_online_configuring_account(cache=False)
-        cmfactory.bring_accounts_online()
 
         lp.sec("ac1: create QR code and let ac2 scan it, starting the securejoin")
-        qr = ac1.get_setup_contact_qr()
+        qr = ac1.get_qr_code()
 
         lp.sec("ac2: start QR-code based setup contact protocol")
-        ch = ac2.qr_setup_contact(qr)
+        ch = ac2.secure_join(qr)
         assert ch.id >= 10
-        ac1._evtracker.wait_securejoin_inviter_progress(1000)
+        ac1.wait_for_securejoin_inviter_success()
 
     def test_dkim_header_stripped(self, cmfactory, maildomain2, lp, imap_mailbox):
         """Test that if a DC address receives a message, it has no
         DKIM-Signature and Authentication-Results headers."""
-        ac1 = cmfactory.new_online_configuring_account(cache=False)
+        ac1 = cmfactory.get_online_account()
-        cmfactory.switch_maildomain(maildomain2)
+        ac2 = cmfactory.get_online_account(domain=maildomain2)
-        ac2 = cmfactory.new_online_configuring_account(cache=False)
-        cmfactory.bring_accounts_online()
         chat = cmfactory.get_accepted_chat(ac1, imap_mailbox.dc_ac)
         chat.send_text("message0")
         chat2 = cmfactory.get_accepted_chat(ac2, imap_mailbox.dc_ac)
@@ -146,29 +143,28 @@ class TestEndToEndDeltaChat:
                 assert "dkim-signature" not in msg.headers
 
     def test_read_receipts_between_instances(self, cmfactory, lp, maildomain2):
-        ac1 = cmfactory.new_online_configuring_account(cache=False)
+        ac1 = cmfactory.get_online_account()
-        cmfactory.switch_maildomain(maildomain2)
+        ac2 = cmfactory.get_online_account(domain=maildomain2)
-        ac2 = cmfactory.new_online_configuring_account(cache=False)
-        cmfactory.bring_accounts_online()
 
         lp.sec("setup encrypted comms between ac1 and ac2 on different instances")
-        qr = ac1.get_setup_contact_qr()
+        qr = ac1.get_qr_code()
-        ch = ac2.qr_setup_contact(qr)
+        ch = ac2.secure_join(qr)
         assert ch.id >= 10
-        ac1._evtracker.wait_securejoin_inviter_progress(1000)
+        ac1.wait_for_securejoin_inviter_success()
 
         lp.sec("ac1 sends a message and ac2 marks it as seen")
         chat = ac1.create_chat(ac2)
         msg = chat.send_text("hi")
-        m = ac2._evtracker.wait_next_incoming_message()
+        m = ac2.wait_for_incoming_msg()
         m.mark_seen()
         # we can only indirectly wait for mark-seen to cause an smtp-error
         lp.sec("try to wait for markseen to complete and check error states")
         deadline = time.time() + 3.1
         while time.time() < deadline:
-            msgs = m.chat.get_messages()
+            m_snap = m.get_snapshot()
+            msgs = m_snap.chat.get_messages()
             for msg in msgs:
-                assert "error" not in m.get_message_info()
+                assert "error" not in m.get_info()
             time.sleep(1)
 
 
@@ -180,7 +176,7 @@ def test_hide_senders_ip_address(cmfactory, ssl_context):
     chat = cmfactory.get_accepted_chat(user1, user2)
 
     chat.send_text("testing submission header cleanup")
-    user2._evtracker.wait_next_incoming_message()
+    user2.wait_for_incoming_msg()
     addr = user2.get_config("addr")
     host = addr.split("@")[1]
     pw = user2.get_config("mail_pw")

cmdeploy/src/cmdeploy/tests/plugin.py

@@ -1,5 +1,4 @@
 import imaplib
-import io
 import itertools
 import os
 import random
@@ -35,17 +34,24 @@ def pytest_runtest_setup(item):
             pytest.skip("skipping slow test, use --slow to run")
 
 
-@pytest.fixture(scope="session")
+def _get_chatmail_config():
-def chatmail_config(pytestconfig):
+    current = Path().resolve()
-    current = basedir = Path().resolve()
     while 1:
         path = current.joinpath("chatmail.ini").resolve()
         if path.exists():
-            return read_config(path)
+            return read_config(path), path
         if current == current.parent:
             break
         current = current.parent
+    return None, None
 
+
+@pytest.fixture(scope="session")
+def chatmail_config(pytestconfig):
+    config, path = _get_chatmail_config()
+    if config:
+        return config
+    basedir = Path().resolve()
     pytest.skip(f"no chatmail.ini file found in {basedir} or parent dirs")
 
 
@@ -73,10 +79,17 @@ def sshdomain2(maildomain2):
 
 
 def pytest_report_header():
-    domain = os.environ.get("CHATMAIL_DOMAIN")
+    config, path = _get_chatmail_config()
-    if domain:
+    domain2 = os.environ.get("CHATMAIL_DOMAIN2", "NOT SET")
-        text = f"chatmail test instance: {domain}"
+    domain = config.mail_domain if config else "NOT SET"
-        return ["-" * len(text), text, "-" * len(text)]
+    path = path if path else "NOT SET"
+
+    lines = [
+        f"chatmail.ini {domain} location: {path}",
+        f"chatmail2: {domain2}",
+    ]
+    sep = "-" * max(map(len, lines))
+    return [sep, *lines, sep]
 
 
 @pytest.fixture
@@ -91,15 +104,22 @@ def cm_data(request):
 
 
 @pytest.fixture
-def benchmark(request):
+def benchmark(request, chatmail_config):
-    def bench(func, num, name=None, reportfunc=None):
+    def bench(func, num, name=None, reportfunc=None, cooldown=0.0):
         if name is None:
             name = func.__name__
+        if cooldown == "auto":
+            per_minute = max(chatmail_config.max_user_send_per_minute, 1)
+            cooldown = chatmail_config.max_user_send_burst_size * 60 / per_minute
+
         durations = []
         for i in range(num):
             now = time.time()
             func()
             durations.append(time.time() - now)
+            if cooldown > 0 and i + 1 < num:
+                # Keep post-run cooldown out of measured benchmark duration.
+                time.sleep(cooldown)
         durations.sort()
         request.config._benchresults[name] = (reportfunc, durations)
 
@@ -276,79 +296,95 @@ def gencreds(chatmail_config):
 
 
 #
-# Delta Chat testplugin re-use
+# Delta Chat RPC-based test support
 # use the cmfactory fixture to get chatmail instance accounts
 #
 
+from deltachat_rpc_client import DeltaChat, Rpc
 
-class ChatmailTestProcess:
-    """Provider for chatmail instance accounts as used by deltachat.testplugin.acfactory"""
 
-    def __init__(self, pytestconfig, maildomain, gencreds, chatmail_config):
+class ChatmailACFactory:
-        self.pytestconfig = pytestconfig
+    """RPC-based account factory for chatmail testing."""
-        self.maildomain = maildomain
+
-        assert "." in self.maildomain, maildomain
+    def __init__(self, rpc, maildomain, gencreds, chatmail_config):
+        self.dc = DeltaChat(rpc)
+        self.rpc = rpc
+        self._maildomain = maildomain
         self.gencreds = gencreds
         self.chatmail_config = chatmail_config
-        self._addr2files = {}
 
-    def get_liveconfig_producer(self):
+    def _make_transport(self, domain):
-        while 1:
+        """Build a transport config dict for the given domain."""
-            user, password = self.gencreds(self.maildomain)
+        addr, password = self.gencreds(domain)
-            config = {
+        transport = {
-                "addr": user,
+            "addr": addr,
-                "mail_pw": password,
+            "password": password,
-            }
+            # Setting server explicitly skips requesting autoconfig XML,
-            # speed up account configuration
+            # see https://datatracker.ietf.org/doc/draft-ietf-mailmaint-autoconfig/
-            config["mail_server"] = self.maildomain
+            "imapServer": domain,
-            config["send_server"] = self.maildomain
+            "smtpServer": domain,
-            if self.chatmail_config.tls_cert_mode == "self":
+        }
-                # Accept self-signed TLS certificates
+        if self.chatmail_config.tls_cert_mode == "self":
-                config["imap_certificate_checks"] = "3"
+            transport["certificateChecks"] = "acceptInvalidCertificates"
-            yield config
+        return transport
 
-    def cache_maybe_retrieve_configured_db_files(self, cache_addr, db_target_path):
+    def get_online_account(self, domain=None):
-        pass
+        """Create, configure and bring online a single account."""
+        return self.get_online_accounts(1, domain)[0]
 
-    def cache_maybe_store_configured_db_files(self, acc):
+    def get_online_accounts(self, num, domain=None):
-        pass
+        """Create multiple online accounts in parallel."""
+        domain = domain or self._maildomain
+        futures = []
+        accounts = []
+        for _ in range(num):
+            account = self.dc.add_account()
+            future = account.add_or_update_transport.future(
+                self._make_transport(domain)
+            )
+            futures.append(future)
+
+            # ensure messages stay in INBOX so that they can be
+            # concurrently fetched via extra IMAP connections during tests
+            account.set_config("delete_server_after", "10")
+            accounts.append(account)
+
+        for future in futures:
+            future()
+
+        for account in accounts:
+            account.bring_online()
+        return accounts
+
+    def get_accepted_chat(self, ac1, ac2):
+        """Create a 1:1 chat between ac1 and ac2 accepted on both sides."""
+        ac2.create_chat(ac1)
+        return ac1.create_chat(ac2)
+
+
+@pytest.fixture(scope="session")
+def rpc(tmp_path_factory):
+    """Start a deltachat-rpc-server process for the test session."""
+
+    # NB: accounts_dir must NOT already exist as directory --
+    # core-rust only creates accounts.toml if the dir doesn't exist yet.
+    accounts_dir = str(tmp_path_factory.mktemp("dc") / "accounts")
+    rpc = Rpc(accounts_dir=accounts_dir)
+    rpc.start()
+    yield rpc
+    rpc.close()
 
 
 @pytest.fixture
-def cmfactory(request, gencreds, tmpdir, maildomain, chatmail_config):
+def cmfactory(rpc, gencreds, maildomain, chatmail_config):
-    # cloned from deltachat.testplugin.amfactory
+    """Return a ChatmailACFactory for creating online Delta Chat accounts."""
-    pytest.importorskip("deltachat")
+    return ChatmailACFactory(
-    from deltachat.testplugin import ACFactory
+        rpc=rpc,
-
+        maildomain=maildomain,
-    testproc = ChatmailTestProcess(
+        gencreds=gencreds,
-        request.config, maildomain, gencreds, chatmail_config
+        chatmail_config=chatmail_config,
     )
 
-    class Data:
-        def read_path(self, path):
-            return
-
-    am = ACFactory(request=request, tmpdir=tmpdir, testprocess=testproc, data=Data())
-
-    # Skip upstream's init_imap to prevent extra imap connections not
-    # needed for relay testing
-    am._acsetup.init_imap = lambda acc: None
-
-    # nb. a bit hacky
-    # would probably be better if deltachat's test machinery grows native support
-    def switch_maildomain(maildomain2):
-        am.testprocess.maildomain = maildomain2
-
-    am.switch_maildomain = switch_maildomain
-
-    yield am
-    if hasattr(request.node, "rep_call") and request.node.rep_call.failed:
-        if testproc.pytestconfig.getoption("--extra-info"):
-            logfile = io.StringIO()
-            am.dump_imap_summary(logfile=logfile)
-            print(logfile.getvalue())
-            # request.node.add_report_section("call", "imap-server-state", s)
-
 
 @pytest.fixture
 def remote(sshdomain):
@@ -359,13 +395,16 @@ class Remote:
     def __init__(self, sshdomain):
         self.sshdomain = sshdomain
 
-    def iter_output(self, logcmd=""):
+    def iter_output(self, logcmd="", ready=None):
         getjournal = "journalctl -f" if not logcmd else logcmd
         print(self.sshdomain)
         match self.sshdomain:
             case "@local": command = []
             case "localhost": command = []
             case _: command = ["ssh", f"root@{self.sshdomain}"]
+        docker_container = os.environ.get("CHATMAIL_DOCKER")
+        if docker_container:
+            command += ["docker", "exec", docker_container]
         [command.append(arg) for arg in getjournal.split()]
         self.popen = subprocess.Popen(
             command,
@@ -374,10 +413,12 @@ class Remote:
         while 1:
             line = self.popen.stdout.readline()
             res = line.decode().strip().lower()
-            if res:
+            if not res:
-                yield res
-            else:
                 break
+            if ready is not None:
+                ready()
+                ready = None
+            yield res
 
 
 @pytest.fixture

cmdeploy/src/cmdeploy/tests/test_external_tls.py

@@ -0,0 +1,78 @@
+"""Functional tests for tls_external_cert_and_key option."""
+
+import json
+
+import chatmaild.newemail
+import pytest
+from chatmaild.config import read_config, write_initial_config
+
+
+def make_external_config(tmp_path, cert_key=None):
+    inipath = tmp_path / "chatmail.ini"
+    overrides = {}
+    if cert_key is not None:
+        overrides["tls_external_cert_and_key"] = cert_key
+    write_initial_config(inipath, "chat.example.org", overrides=overrides)
+    return inipath
+
+
+def test_external_tls_config_reads_paths(tmp_path):
+    inipath = make_external_config(
+        tmp_path,
+        cert_key=(
+            "/etc/letsencrypt/live/chat.example.org/fullchain.pem"
+            " /etc/letsencrypt/live/chat.example.org/privkey.pem"
+        ),
+    )
+    config = read_config(inipath)
+    assert config.tls_cert_mode == "external"
+    assert (
+        config.tls_cert_path == "/etc/letsencrypt/live/chat.example.org/fullchain.pem"
+    )
+    assert config.tls_key_path == "/etc/letsencrypt/live/chat.example.org/privkey.pem"
+
+
+def test_external_tls_missing_option_uses_acme(tmp_path):
+    config = read_config(make_external_config(tmp_path))
+    assert config.tls_cert_mode == "acme"
+
+
+def test_external_tls_bad_format_raises(tmp_path):
+    inipath = make_external_config(tmp_path, cert_key="/only/one/path.pem")
+    with pytest.raises(ValueError, match="two space-separated"):
+        read_config(inipath)
+
+
+def test_external_tls_three_paths_raises(tmp_path):
+    inipath = make_external_config(tmp_path, cert_key="/a /b /c")
+    with pytest.raises(ValueError, match="two space-separated"):
+        read_config(inipath)
+
+
+def test_external_tls_no_dclogin_url(tmp_path, capsys, monkeypatch):
+    inipath = make_external_config(
+        tmp_path, cert_key="/certs/fullchain.pem /certs/privkey.pem"
+    )
+    monkeypatch.setattr(chatmaild.newemail, "CONFIG_PATH", str(inipath))
+    chatmaild.newemail.print_new_account()
+    out, _ = capsys.readouterr()
+    lines = out.split("\n")
+    dic = json.loads(lines[2])
+    assert "dclogin_url" not in dic
+
+
+def test_external_tls_selects_correct_deployer(tmp_path):
+    from cmdeploy.deployers import get_tls_deployer
+    from cmdeploy.external.deployer import ExternalTlsDeployer
+    from cmdeploy.selfsigned.deployer import SelfSignedTlsDeployer
+
+    inipath = make_external_config(
+        tmp_path, cert_key="/certs/fullchain.pem /certs/privkey.pem"
+    )
+    config = read_config(inipath)
+    deployer = get_tls_deployer(config, "chat.example.org")
+
+    assert isinstance(deployer, ExternalTlsDeployer)
+    assert not isinstance(deployer, SelfSignedTlsDeployer)
+    assert deployer.cert_path == "/certs/fullchain.pem"
+    assert deployer.key_path == "/certs/privkey.pem"

doc/source/docker.rst

@@ -0,0 +1,266 @@
+Docker installation
+===================
+
+This section provides instructions for installing a chatmail relay
+using Docker Compose.
+
+.. note::
+
+    - Docker support is experimental, CI builds and tests the image automatically, but please report bugs.
+    - The image wraps the cmdeploy process detailed in the :doc:`getting_started` instructions in a Debian-systemd image with r/w access to `/sys/fs`
+    - Currently amd64-only (arm64 should work but is untested).
+
+
+Setup Preparation
+-----------------
+
+We use ``chat.example.org`` as the chatmail domain in the following
+steps. Please substitute it with your own domain.
+
+1. Install docker and docker compose v2 (check with `docker compose version`), install, e.g., through
+    - Debian 12 through the `official install instructions <https://docs.docker.com/engine/install/debian/#install-using-the-repository>`_
+    - Debian 13+ with `apt install docker docker-compose`
+
+   If you must use v1 (EOL since 2023), use `docker-compose` in the following and modify the `docker-compose.yaml` to use `privileged: true` instead of `cgroup: host`, though that gives the container full privileges.
+
+2. Setup the initial DNS records.
+   The following is an example in the familiar BIND zone file format with
+   a TTL of 1 hour (3600 seconds).
+   Please substitute your domain and IP addresses.
+
+   ::
+
+       chat.example.org. 3600 IN A 198.51.100.5
+       chat.example.org. 3600 IN AAAA 2001:db8::5
+       www.chat.example.org. 3600 IN CNAME chat.example.org.
+       mta-sts.chat.example.org. 3600 IN CNAME chat.example.org.
+
+3. Configure kernel parameters on the host, as these can not be set from the container::
+
+       echo "fs.inotify.max_user_instances=65536" | sudo tee -a /etc/sysctl.d/99-inotify.conf
+       echo "fs.inotify.max_user_watches=65536" | sudo tee -a /etc/sysctl.d/99-inotify.conf
+       sudo sysctl --system
+
+
+Docker Compose Setup
+--------------------
+
+Pre-built images are available from GitHub Container Registry. The
+``main`` branch and tagged releases are pushed automatically by CI::
+
+    docker pull ghcr.io/chatmail/relay:main      # latest main branch
+    docker pull ghcr.io/chatmail/relay:1.2.3     # tagged release
+
+
+Create service directory
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+    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
+
+
+Customize and start
+^^^^^^^^^^^^^^^^^^^
+
+1. Set the fully qualified domain name of the relay::
+
+       echo 'MAIL_DOMAIN=chat.example.org' > .env
+
+   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
+       docker compose logs -f chatmail   # view logs, Ctrl+C to exit
+
+4. After installation is complete, open ``https://chat.example.org`` in
+   your browser.
+
+Finish install and test
+-----------------------
+
+You can test the installation with::
+
+        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 cmdeploy dns --ssh-host @local
+
+You can check server status with::
+
+    docker exec chatmail cmdeploy status --ssh-host @local
+
+You can run some benchmarks (can also run from any machine with cmdeploy installed)::
+
+    docker exec chatmail cmdeploy bench
+
+You can run the test suite with::
+
+    docker exec chatmail cmdeploy test --ssh-host localhost
+
+You can look at logs::
+
+    docker exec chatmail journalctl -fu postfix@-
+
+
+Customization
+-------------
+
+Website
+^^^^^^^^^^^^^^
+
+You can customize the chatmail landing page by mounting a directory with
+your own website source files.
+
+1. Create a directory with your custom website source::
+
+       mkdir -p ./custom/www/src
+       nano ./custom/www/src/index.md
+
+2. Add the volume mount in ``docker-compose.override.yaml``::
+
+       services:
+         chatmail:
+           volumes:
+             - ./custom/www:/opt/chatmail-www
+
+3. Restart the service::
+
+       docker compose down
+       docker compose up -d
+
+
+Custom chatmail.ini
+^^^^^^^^^^^^^^^^^^^
+
+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.
+
+1. Extract the generated config from a running container::
+
+       docker cp chatmail:/etc/chatmail/chatmail.ini ./chatmail.ini
+
+2. Edit ``chatmail.ini`` as needed.
+
+3. Add the volume mount in ``docker-compose.override.yaml`` ::
+
+       services:
+         chatmail:
+           volumes:
+             - ./chatmail.ini:/etc/chatmail/chatmail.ini
+
+4. Restart the container, the container skips generating a new one: ::
+
+       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
+------------------------------------
+
+If you have an existing bare-metal chatmail installation and want to
+switch to Docker:
+
+1. Stop all existing services::
+
+       systemctl stop postfix dovecot doveauth nginx opendkim unbound \
+         acmetool-redirector filtermail filtermail-incoming chatmail-turn \
+         iroh-relay chatmail-metadata lastlogin mtail
+       systemctl disable postfix dovecot doveauth nginx opendkim unbound \
+         acmetool-redirector filtermail filtermail-incoming chatmail-turn \
+         iroh-relay chatmail-metadata lastlogin mtail
+
+2. Copy your existing ``chatmail.ini`` and mount it into the container
+   (see `Custom chatmail.ini`_ above)::
+
+       cp /usr/local/lib/chatmaild/chatmail.ini ./chatmail.ini
+
+3. Copy persistent data into the ``./data/`` subdirectories (for example, as configured in `Customize and start`_) ::
+
+       mkdir -p data/dkim data/certs data/mail
+
+       # DKIM keys
+       cp -a /etc/dkimkeys/* data/dkim/
+
+       # TLS certificates
+       rsync -a /var/lib/acme/ data/certs/
+
+   Note that ownership of dkim and acme is adjusted on container start.
+
+   For the mail directory::
+
+       rsync -a /home/vmail/ data/mail/
+
+   Alternatively, mount ``/home/vmail`` directly by changing the volume
+   in ``docker-compose-override.yaml``::
+
+       - /home/vmail:/home/vmail
+
+   The three ``./data/`` subdirectories cover all persistent state.
+   Everything else is regenerated by the ``configure`` and ``activate``
+   stages on container start.
+
+Building the image
+------------------
+
+Clone the repository and build the Docker image::
+
+    git clone https://github.com/chatmail/relay
+    cd relay
+    docker/build.sh
+
+The build bakes all binaries, Python packages, and the install stage
+into the image. After building, only ``docker-compose.yaml`` and a ``.env``
+with ``MAIL_DOMAIN`` are needed to run the container. The `build.sh` passes the
+git hash onto the docker build so it can be determined if there has been a
+change that warrants a redeploy.
+
+You can transfer a locally built image to your server directly (pigz is parallel `gzip` which can be used instead as well) ::
+
+    docker save chatmail-relay:latest | pigz | ssh chat.example.org 'pigz -d | docker load'
+
+
+Forcing a full reinstall
+------------------------
+
+On container start, only the ``configure`` and ``activate`` stages run by default.
+
+To force a full reinstall (e.g. after updating the source), either
+rebuild the image::
+
+    docker compose build chatmail
+    docker compose up -d
+
+Or override the stages at runtime without rebuilding::
+
+    CMDEPLOY_STAGES="install,configure,activate" docker compose up -d

doc/source/getting_started.rst

@@ -98,6 +98,12 @@ steps. Please substitute it with your own domain.
    configure at your DNS provider (it can take some time until they are
    public).
 
+Docker installation
+-------------------
+
+There is experimental support for running chatmail via Docker Compose.
+See :doc:`docker` for full setup instructions.
+
 Other helpful commands
 ----------------------
 
@@ -198,6 +204,44 @@ and all other relays will accept connections from it
 without requiring certificate verification.
 This is useful for experimental setups and testing.
 
+.. _external-tls:
+
+Running a relay with externally managed certificates
+-----------------------------------------------------
+
+If you already have a TLS certificate manager
+(e.g. Traefik, certbot, or another ACME client)
+running on the deployment server,
+you can configure the relay to use those certificates
+instead of the built-in ``acmetool``.
+
+Set the following in ``chatmail.ini``::
+
+    tls_external_cert_and_key = /path/to/fullchain.pem /path/to/privkey.pem
+
+The paths must point to certificate and key files
+on the deployment server.
+During ``cmdeploy run``, these paths are written into
+the Postfix, Dovecot, and Nginx configurations.
+No certificate files are transferred from the build machine —
+they must already exist on the server,
+managed by your external certificate tool.
+
+The deploy will verify that both files exist on the server.
+``acmetool`` is **not** installed or run in this mode.
+
+.. note::
+
+   You are responsible for certificate renewal.
+   When the certificate file changes on disk,
+   all relay services pick up the new certificate automatically
+   via a systemd path watcher installed during deploy.
+   The watcher uses inotify, which does not cross bind-mount boundaries.
+   If you use such a setup, you must trigger the reload explicitly after renewal::
+
+      systemctl start tls-cert-reload.service
+
+
 Migrating to a new build machine
 ----------------------------------
 

doc/source/index.rst

@@ -13,6 +13,7 @@ Contributions and feedback welcome through the https://github.com/chatmail/relay
     :maxdepth: 5
 
     getting_started
+    docker
     proxy
     migrate
     overview

doc/source/overview.rst

@@ -308,6 +308,11 @@ When providing a TLS certificate to your chatmail relay server, make
 sure to provide the full certificate chain and not just the last
 certificate.
 
+If you use an external certificate manager (e.g. Traefik or certbot),
+set ``tls_external_cert_and_key`` in ``chatmail.ini``
+to provide the certificate and key paths.
+See :ref:`external-tls` for details.
+
 If you are running an Exim server and don’t see incoming connections
 from a chatmail relay server in the logs, make sure ``smtp_no_mail`` log
 item is enabled in the config with ``log_selector = +smtp_no_mail``. By

docker-compose.override.yaml.example

@@ -0,0 +1,44 @@
+# Local overrides: copy to docker-compose.override.yaml in the repo root.
+# Compose automatically merges this with docker-compose.yaml.
+#
+#   cp docker-compose.override.yaml.example docker-compose.override.yaml
+#
+# Volumes are APPENDED to the base file's volumes list, environment and other scalar keys are MERGED by key.
+services:
+  chatmail:
+    volumes:
+      ## Data paths — bind-mount to host directories for easy access/backup.
+
+      # - ./data/dkim:/etc/dkimkeys
+      # - ./data/certs:/var/lib/acme
+
+      # - ./data/mail:/home/vmail
+      ## Or mount 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/chatmail-init.sh:/chatmail-init.sh
+      # - ./docker/entrypoint.sh:/entrypoint.sh
+
+    # environment:
+      ## Mount certs (above) and set TLS_EXTERNAL_CERT_AND_KEY to in-container paths.
+      ## A tls-cert-reload.path watcher inside the container reloads services
+      ## when the cert file changes. However, inotify does not cross bind-mount
+      ## boundaries, so host-side renewals (certbot, acmetool, etc.) must
+      ## notify the container explicitly. Add this to your renewal hook:
+      ##
+      ##   docker exec chatmail systemctl start tls-cert-reload.service
+      ##
+      ## Host acmetool (bare-metal migration): create mount above, and
+      ##   rsync -a /var/lib/acme/live data/certs
+      # TLS_EXTERNAL_CERT_AND_KEY: "/var/lib/acme/live/${MAIL_DOMAIN}/fullchain /var/lib/acme/live/${MAIL_DOMAIN}/privkey"
+      ##
+      ## (Untested) 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

@@ -0,0 +1,48 @@
+# 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 notes: this container uses 
+#  - network_mode:host chatmail needs many ports (25, 53, 80, 143, 443, 465,
+#  587, 993, 3340, 8443) and needs to operate from the real IP, which bridging
+#  would make tricky
+#  - cgroup:host (required for systemd). 
+#  Together these give the container near-host-level access. This is acceptable
+#  for a dedicated mail server, but be aware that the container can bind any
+#  port and see all host network traffic.
+
+services:
+  chatmail:
+    build:
+      context: ./
+      dockerfile: docker/chatmail_relay.dockerfile
+      args:
+        GIT_HASH: ${GIT_HASH:-unknown}
+    image: chatmail-relay:latest
+    restart: unless-stopped
+    container_name: chatmail
+    # Required for systemd — use only one of the following:
+    cgroup: host          # compose v2
+    # privileged: true    # compose v1 (less restricted)
+    tty: true # required for logs
+    tmpfs: # required for systemd
+      - /tmp
+      - /run
+      - /run/lock
+    logging:
+      driver: none
+    environment:
+      MAIL_DOMAIN: $MAIL_DOMAIN
+    network_mode: "host"
+    volumes:
+      ## system (required)
+      - /sys/fs/cgroup:/sys/fs/cgroup:rw
+      ## data (defaults — override in docker-compose.override.yaml)
+      - mail:/home/vmail
+      - dkim:/etc/dkimkeys
+      - certs:/var/lib/acme
+
+volumes:
+  mail:
+  dkim:
+  certs:

docker/build.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Build the chatmail Docker image with the current git hash baked in.
+# Usage: ./docker/build.sh [extra docker-compose build args...]
+#
+# .git/ is excluded from the build context (.dockerignore) so the hash
+# must be passed as a build arg from the host.
+
+export GIT_HASH=$(git rev-parse HEAD)
+exec docker compose build "$@"

docker/chatmail-init.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=Run container setup commands
+After=multi-user.target
+ConditionPathExists=/chatmail-init.sh
+
+[Service]
+Type=oneshot
+ExecStart=/bin/bash /chatmail-init.sh
+RemainAfterExit=true
+WorkingDirectory=/opt/chatmail
+PassEnvironment=<envs_list>
+
+[Install]
+WantedBy=multi-user.target

docker/chatmail-init.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+
+set -euo pipefail
+export CHATMAIL_INI="${CHATMAIL_INI:-/etc/chatmail/chatmail.ini}"
+export CHATMAIL_NOSYSCTL=True
+export CHATMAIL_NOPORTCHECK=True
+
+CMDEPLOY=/opt/cmdeploy/bin/cmdeploy
+
+if [ -z "$MAIL_DOMAIN" ]; then
+    echo "ERROR: Environment variable 'MAIL_DOMAIN' must be set!" >&2
+    exit 1
+fi
+
+# Generate DKIM keys if not mounted
+if [ ! -f /etc/dkimkeys/opendkim.private ]; then
+    /usr/sbin/opendkim-genkey -D /etc/dkimkeys -d "$MAIL_DOMAIN" -s opendkim
+fi
+# Fix ownership for bind-mounted keys (host opendkim UID may differ from container)
+chown -R opendkim:opendkim /etc/dkimkeys
+
+# Create chatmail.ini, skip if mounted
+mkdir -p "$(dirname "$CHATMAIL_INI")"
+if [ ! -f "$CHATMAIL_INI" ]; then
+    $CMDEPLOY init --config "$CHATMAIL_INI" "$MAIL_DOMAIN"
+fi
+
+# Auto-detect IPv6: if the host has no IPv6 connectivity, set disable_ipv6
+# in the ini so dovecot/postfix/nginx bind to IPv4 only.
+# Uses network_mode:host so /proc/net/if_inet6 reflects the host's stack.
+if [ ! -e /proc/net/if_inet6 ]; then
+    if grep -q '^disable_ipv6 = False' "$CHATMAIL_INI"; then
+        sed -i 's/^disable_ipv6 = False/disable_ipv6 = True/' "$CHATMAIL_INI"
+        echo "[INFO] IPv6 not available, set disable_ipv6 = True"
+    fi
+fi
+
+# Inject external TLS paths from env var unless defined in chatmail.ini
+if [ -n "${TLS_EXTERNAL_CERT_AND_KEY:-}" ]; then
+    if ! grep -q '^tls_external_cert_and_key' "$CHATMAIL_INI"; then
+        echo "tls_external_cert_and_key = $TLS_EXTERNAL_CERT_AND_KEY" >> "$CHATMAIL_INI"
+    fi
+fi
+
+# Ensure mailboxes directory exists (chatmail-metadata needs it at startup,
+# but Dovecot only creates it on first mail delivery)
+mkdir -p "/home/vmail/mail/${MAIL_DOMAIN}"
+chown vmail:vmail "/home/vmail/mail/${MAIL_DOMAIN}"
+
+# --- Deploy fingerprint: skip cmdeploy run if nothing changed ---
+# On restart with identical image+config, systemd already brings up all
+# enabled services only configure+activate are needed here.
+IMAGE_VERSION_FILE="/etc/chatmail-image-version"
+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
+    export CMDEPLOY_STAGES="${CMDEPLOY_STAGES:-configure,activate}"
+
+    # Skip DNS check when MAIL_DOMAIN is a bare IP address
+    SKIP_DNS=""
+    if [[ "$MAIL_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]] || [[ "$MAIL_DOMAIN" =~ : ]]; then
+        SKIP_DNS="--skip-dns-check"
+    fi
+    $CMDEPLOY run --config "$CHATMAIL_INI" --ssh-host @local $SKIP_DNS
+
+    # Restore the build-time hash
+    cp /etc/chatmail-image-version /etc/chatmail-version
+    echo "$current_fp" > "$FINGERPRINT_FILE"
+fi
+
+# Signal success to Docker healthcheck
+touch /run/chatmail-init.done
+
+# Forward journald to console so `docker compose logs` works
+grep -q '^ForwardToConsole=yes' /etc/systemd/journald.conf \
+    || echo "ForwardToConsole=yes" >> /etc/systemd/journald.conf
+systemctl restart systemd-journald

docker/chatmail_relay.dockerfile

@@ -0,0 +1,101 @@
+# syntax=docker/dockerfile:1
+FROM jrei/systemd-debian:12 AS base
+
+ENV LANG=en_US.UTF-8
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \
+    echo 'APT::Install-Recommends "0";' > /etc/apt/apt.conf.d/01norecommend && \
+    echo 'APT::Install-Suggests "0";' >> /etc/apt/apt.conf.d/01norecommend && \
+    apt-get update && \
+    DEBIAN_FRONTEND=noninteractive TZ=UTC \
+    apt-get install -y \
+        ca-certificates \
+        gcc \
+        git \
+        python3 \
+        python3-dev \
+        python3-venv \
+        tzdata \
+        locales && \
+    sed -i -e "s/# $LANG.*/$LANG UTF-8/" /etc/locale.gen && \
+    dpkg-reconfigure --frontend=noninteractive locales && \
+    update-locale LANG=$LANG
+
+# --- Build-time: install cmdeploy venv and run install stage ---
+# Editable install so importlib.resources reads directly from the source tree.
+# On container start only "configure,activate" stages run.
+
+# Copy dependency metadata first so pip install layer is cached
+COPY cmdeploy/pyproject.toml /opt/chatmail/cmdeploy/pyproject.toml
+COPY chatmaild/pyproject.toml /opt/chatmail/chatmaild/pyproject.toml
+
+# Dummy scaffolding so editable install can discover packages
+RUN mkdir -p /opt/chatmail/cmdeploy/src/cmdeploy \
+             /opt/chatmail/chatmaild/src/chatmaild && \
+    touch /opt/chatmail/cmdeploy/src/cmdeploy/__init__.py \
+          /opt/chatmail/chatmaild/src/chatmaild/__init__.py
+
+# Dummy git repo: .git/ is excluded from the build context (.dockerignore)
+# but setuptools calls `git ls-files` when building the sdist.
+WORKDIR /opt/chatmail
+RUN --mount=type=cache,target=/root/.cache/pip \
+    git init -q && \
+    python3 -m venv /opt/cmdeploy && \
+    /opt/cmdeploy/bin/pip install -e chatmaild/ -e cmdeploy/
+
+# Full source copy (editable install's .egg-link still points here)
+COPY . /opt/chatmail/
+
+# Minimal chatmail.ini
+RUN printf '[params]\nmail_domain = build.local\n' > /tmp/chatmail.ini
+
+RUN CMDEPLOY_STAGES=install \
+    CHATMAIL_INI=/tmp/chatmail.ini \
+    CHATMAIL_NOSYSCTL=True \
+    CHATMAIL_NOPORTCHECK=True \
+    /opt/cmdeploy/bin/pyinfra @local \
+        /opt/chatmail/cmdeploy/src/cmdeploy/run.py -y
+
+RUN cp -a www/ /opt/chatmail-www/
+
+# Remove build-only packages and their deps — not needed at runtime
+RUN apt-get purge -y gcc git python3-dev && \
+    apt-get autoremove -y && \
+    rm -f /tmp/chatmail.ini
+
+# Record image version (used in deploy fingerprint at runtime).
+# GIT_HASH is passed as a build arg (from docker-compose or CI) so that
+# .git/ can be excluded from the build context via .dockerignore.
+# Two files: chatmail-image-version is the immutable build hash (survives
+# deploys); chatmail-version is overwritten by cmdeploy run and restored
+# from the image version after each deploy in chatmail-init.sh.
+ARG GIT_HASH=unknown
+RUN echo "$GIT_HASH" > /etc/chatmail-image-version && \
+    echo "$GIT_HASH" > /etc/chatmail-version
+# --- End build-time install ---
+
+ENV TZ=:/etc/localtime
+ENV PATH="/opt/cmdeploy/bin:${PATH}"
+RUN ln -s /etc/chatmail/chatmail.ini /opt/chatmail/chatmail.ini
+
+ARG CHATMAIL_INIT_SERVICE_PATH=/lib/systemd/system/chatmail-init.service
+COPY ./docker/chatmail-init.service "$CHATMAIL_INIT_SERVICE_PATH"
+RUN ln -sf "$CHATMAIL_INIT_SERVICE_PATH" "/etc/systemd/system/multi-user.target.wants/chatmail-init.service"
+
+# Remove default nginx site config at build time (not in entrypoint)
+RUN rm -f /etc/nginx/sites-enabled/default
+
+COPY --chmod=555 ./docker/chatmail-init.sh /chatmail-init.sh
+COPY --chmod=555 ./docker/entrypoint.sh /entrypoint.sh
+COPY --chmod=555 ./docker/healthcheck.sh /healthcheck.sh
+
+HEALTHCHECK --interval=10s --start-period=180s --timeout=10s --retries=3 \
+  CMD /healthcheck.sh
+
+STOPSIGNAL SIGRTMIN+3
+
+ENTRYPOINT ["/entrypoint.sh"]
+
+CMD [   "--default-standard-output=journal+console", \
+        "--default-standard-error=journal+console" ]

docker/docker-compose.ci.yaml

@@ -0,0 +1,11 @@
+# Used by .github/workflows/docker-ci.yaml
+# The GHCR image is set via CHATMAIL_IMAGE env var at deploy time.
+services:
+  chatmail:
+    image: ${CHATMAIL_IMAGE:-chatmail-relay:latest}
+    volumes:
+      - /srv/chatmail/chatmail.ini:/etc/chatmail/chatmail.ini
+      - /srv/chatmail/dkim:/etc/dkimkeys
+      - /srv/chatmail/certs:/var/lib/acme
+    environment:
+      TLS_EXTERNAL_CERT_AND_KEY: /var/lib/acme/live/${MAIL_DOMAIN}/fullchain /var/lib/acme/live/${MAIL_DOMAIN}/privkey

docker/entrypoint.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+set -eo pipefail
+
+CHATMAIL_INIT_SERVICE_PATH="${CHATMAIL_INIT_SERVICE_PATH:-/lib/systemd/system/chatmail-init.service}"
+
+env_vars="MAIL_DOMAIN CMDEPLOY_STAGES CHATMAIL_INI TLS_EXTERNAL_CERT_AND_KEY PATH"
+sed -i "s|<envs_list>|$env_vars|g" "$CHATMAIL_INIT_SERVICE_PATH"
+
+exec /lib/systemd/systemd "$@"

docker/healthcheck.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# returns 0 when chatmail-init succeeded and all expected services are running.
+
+set -e
+
+test -f /run/chatmail-init.done
+
+# Core services
+services="chatmail-metadata doveauth dovecot filtermail filtermail-incoming nginx postfix unbound"
+
+# Optional services
+for svc in iroh-relay turnserver; do
+    systemctl is-enabled "$svc" 2>/dev/null && services="$services $svc"
+done
+
+exec systemctl is-active $services

env.example

@@ -0,0 +1 @@
+MAIL_DOMAIN=chat.example.com