docker: integrate documentation

delete original markdown notes (the russian version was severely
outdated) and add a new section.

.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/docker-build.yaml

@@ -0,0 +1,76 @@
+name: Docker Build
+
+on:
+  pull_request:
+    paths:
+      - 'docker/**'
+      - 'docker-compose.yaml'
+      - '.dockerignore'
+      - 'chatmaild/**'
+      - 'cmdeploy/**'
+      - '.github/workflows/docker-build.yaml'
+  push:
+    branches:
+      - main
+      - j4n/docker
+    paths:
+      - 'docker/**'
+      - 'docker-compose.yaml'
+      - '.dockerignore'
+      - 'chatmaild/**'
+      - 'cmdeploy/**'
+      - '.github/workflows/docker-build.yaml'
+    tags:
+      - 'v*'
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    name: Build Docker image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    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: j4n/docker → :j4n-docker
+            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 }}

.gitignore

@@ -164,3 +164,9 @@ cython_debug/
 #.idea/
 
 chatmail.zone
+
+# docker
+/data/
+/custom/
+docker-compose.override.yaml
+.env

CHANGELOG.md

@@ -121,6 +121,13 @@
   Provide an "fsreport" CLI for more fine grained analysis of message files. 
   ([#637](https://github.com/chatmail/relay/pull/637))
 
+- Add installation via docker compose (MVP 1). The instructions, known issues and limitations are located in `/docs` 
+  ([#614](https://github.com/chatmail/relay/pull/614))
+
+- Add configuration parameters
+  ([#614](https://github.com/chatmail/relay/pull/614)):
+  - `change_kernel_settings` - Whether to change kernel parameters during installation (default: `True`)
+  - `fs_inotify_max_user_instances_and_watchers` - Value for kernel parameters `fs.inotify.max_user_instances` and `fs.inotify.max_user_watches` (default: `65535`)
 
 ## 1.7.0 2025-09-11
 

chatmaild/src/chatmaild/config.py

@@ -44,6 +44,7 @@ class Config:
         )
         self.mtail_address = params.get("mtail_address")
         self.disable_ipv6 = params.get("disable_ipv6", "false").lower() == "true"
+        self.noacme = os.environ.get("CHATMAIL_NOACME", "false").lower() == "true"
         self.addr_v4 = os.environ.get("CHATMAIL_ADDR_V4", "")
         self.addr_v6 = os.environ.get("CHATMAIL_ADDR_V6", "")
         self.acme_email = params.get("acme_email", "")

chatmaild/src/chatmaild/tests/test_filtermail_blackbox.py

@@ -57,10 +57,19 @@ def test_one_mail(
     path = str(config._inipath)
 
     popen = make_popen(["filtermail", path, filtermail_mode])
-    line = popen.stderr.readline().strip()
-    if b"loop" not in line:
-        print(line.decode("ascii"), file=sys.stderr)
-        pytest.fail("starting filtermail failed")
+
+    # Wait for filtermail to start accepting connections
+    import socket
+    import time
+    for _ in range(50):  # 5 second timeout
+        try:
+            sock = socket.create_connection(("127.0.0.1", smtp_inject_port), timeout=0.1)
+            sock.close()
+            break
+        except (ConnectionRefusedError, OSError):
+            time.sleep(0.1)
+    else:
+        pytest.fail("filtermail failed to start accepting connections")
 
     addr = f"user1@{config.mail_domain}"
     config.get_user(addr).set_password("l1k2j3l1k2j3l")

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

@@ -109,6 +109,9 @@ def run_cmd(args, out):
 
     cmd = f"{pyinf} --ssh-user root {ssh_host} {deploy_path} -y"
     if ssh_host in ["localhost", "@docker"]:
+        if ssh_host == "@docker":
+            env["CHATMAIL_NOPORTCHECK"] = "True"
+            env["CHATMAIL_NOSYSCTL"] = "True"
         cmd = f"{pyinf} @local {deploy_path} -y"
 
     if version.parse(pyinfra.__version__) < version.parse("3"):
@@ -328,7 +331,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",
     )

cmdeploy/src/cmdeploy/deployers.py

@@ -2,6 +2,7 @@
 Chat Mail pyinfra deploy.
 """
 
+import os
 import shutil
 import subprocess
 import sys
@@ -25,6 +26,7 @@ from .basedeploy import (
     activate_remote_units,
     configure_remote_units,
     get_resource,
+    has_systemd,
 )
 from .dovecot.deployer import DovecotDeployer
 from .filtermail.deployer import FiltermailDeployer
@@ -65,6 +67,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(
@@ -299,7 +303,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",
@@ -566,34 +570,35 @@ 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 = [
-        (["master", "smtpd"], 25),
-        ("unbound", 53),
-        ("acmetool", 80),
-        (["imap-login", "dovecot"], 143),
-        ("nginx", 443),
-        (["master", "smtpd"], 465),
-        (["master", "smtpd"], 587),
-        (["imap-login", "dovecot"], 993),
-        ("iroh-relay", 3340),
-        ("mtail", 3903),
-        ("stats", 3904),
-        ("nginx", 8443),
-        (["master", "smtpd"], config.postfix_reinject_port),
-        (["master", "smtpd"], config.postfix_reinject_port_incoming),
-        ("filtermail", config.filtermail_smtp_port),
-        ("filtermail", config.filtermail_smtp_port_incoming),
-    ]
-    for service, port in port_services:
-        print(f"Checking if port {port} is available for {service}...")
-        running_service = host.get_fact(Port, port=port)
-        services = [service] if isinstance(service, str) else service
-        if running_service:
-            if running_service not in services:
-                Out().red(
-                    f"Deploy failed: port {port} is occupied by: {running_service}"
-                )
-                exit(1)
+    if not os.environ.get("CHATMAIL_NOPORTCHECK"):
+        port_services = [
+            (["master", "smtpd"], 25),
+            ("unbound", 53),
+            ("acmetool", 80),
+            (["imap-login", "dovecot"], 143),
+            ("nginx", 443),
+            (["master", "smtpd"], 465),
+            (["master", "smtpd"], 587),
+            (["imap-login", "dovecot"], 993),
+            ("iroh-relay", 3340),
+            ("mtail", 3903),
+            ("stats", 3904),
+            ("nginx", 8443),
+            (["master", "smtpd"], config.postfix_reinject_port),
+            (["master", "smtpd"], config.postfix_reinject_port_incoming),
+            ("filtermail", config.filtermail_smtp_port),
+            ("filtermail", config.filtermail_smtp_port_incoming),
+        ]
+        for service, port in port_services:
+            print(f"Checking if port {port} is available for {service}...")
+            running_service = host.get_fact(Port, port=port)
+            services = [service] if isinstance(service, str) else service
+            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}"]
 
@@ -605,7 +610,12 @@ def deploy_chatmail(config_path: Path, disable_mail: bool, website_only: bool) -
         UnboundDeployer(config),
         TurnDeployer(mail_domain),
         IrohDeployer(config.enable_iroh_relay),
-        AcmetoolDeployer(config.acme_email, tls_domains),
+    ]
+
+    if not config.noacme:
+        all_deployers.append(AcmetoolDeployer(config.acme_email, tls_domains))
+
+    all_deployers += [
         WebsiteDeployer(config),
         ChatmailVenvDeployer(config),
         MtastsDeployer(),

cmdeploy/src/cmdeploy/dovecot/deployer.py

@@ -1,3 +1,5 @@
+import os
+
 from chatmaild.config import Config
 from pyinfra import host
 from pyinfra.facts.server import Arch, Sysctl
@@ -9,6 +11,7 @@ from cmdeploy.basedeploy import (
     activate_remote_units,
     configure_remote_units,
     get_resource,
+    has_systemd,
 )
 
 
@@ -22,10 +25,11 @@ class DovecotDeployer(Deployer):
 
     def install(self):
         arch = host.get_fact(Arch)
-        if not "dovecot.service" in host.get_fact(SystemdEnabled):
-            _install_dovecot_package("core", arch)
-            _install_dovecot_package("imapd", arch)
-            _install_dovecot_package("lmtpd", arch)
+        if has_systemd() and "dovecot.service" in host.get_fact(SystemdEnabled):
+            return  # already installed and running
+        _install_dovecot_package("core", arch)
+        _install_dovecot_package("imapd", arch)
+        _install_dovecot_package("lmtpd", arch)
 
     def configure(self):
         configure_remote_units(self.config.mail_domain, self.units)
@@ -116,18 +120,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"):
-        key = f"fs.inotify.{name}"
-        if host.get_fact(Sysctl)[key] > 65535:
-            # Skip updating limits if already sufficient
-            # (enables running in incus containers where sysctl readonly)
-            continue
-        server.sysctl(
-            name=f"Change {key}",
-            key=key,
-            value=65535,
-            persist=True,
-        )
+    if not os.environ.get("CHATMAIL_NOSYSCTL"):
+        for name in ("max_user_instances", "max_user_watches"):
+            key = f"fs.inotify.{name}"
+            if host.get_fact(Sysctl)[key] > 65535:
+                # Skip updating limits if already sufficient
+                # (enables running in incus containers where sysctl readonly)
+                continue
+            server.sysctl(
+                name=f"Change {key}",
+                key=key,
+                value=65535,
+                persist=True,
+            )
 
     timezone_env = files.line(
         name="Set TZ environment variable",

cmdeploy/src/cmdeploy/sshexec.py

@@ -89,6 +89,11 @@ class LocalExec:
         self.verbose = verbose
         self.docker = docker
 
+    def __call__(self, call, kwargs=None, log_callback=None):
+        if kwargs is None:
+            kwargs = {}
+        return call(**kwargs)
+
     def logged(self, call, kwargs: dict):
         where = "locally"
         if self.docker:

doc/source/docker.rst

@@ -0,0 +1,262 @@
+Docker installation
+===================
+
+This section provides instructions for installing a chatmail relay
+using Docker Compose.
+
+.. note::
+
+   Docker support is experimental and not yet covered by automated tests, please report bugs.
+
+
+Known limitations
+-----------------
+
+- Requires cgroups v2 on the host. Operation with cgroups v1 has not been tested.
+- This preliminary image simply wraps the cmdeploy process detailed in the :doc:`getting_started` instructions in a full Debian-systemd image. 
+- Currently, the image has only been tested and built on amd64, though arm64 should theoretically work as well.
+
+
+Prerequisites
+-------------
+
+- **Docker Compose v2** (``docker compose``, not ``docker-compose``) is
+  required for its ``cgroup: host`` support (`Install instructions <https://docs.docker.com/engine/install/debian/#install-using-the-repository>`_:)
+
+- **DNS records** for your domain (see step 1 below).
+
+- **Kernel parameters** — ``fs.inotify.max_user_instances`` and
+  ``fs.inotify.max_user_watches`` must be raised on the host because they
+  cannot be changed inside the container (see step 2 below).
+
+
+Preliminary setup
+-----------------
+
+We use ``chat.example.org`` as the chatmail domain in the following
+steps. Please substitute it with your own domain.
+
+1. 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.
+
+2. 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 https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker-compose.override.yaml.example
+    wget https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker/env.example -O .env
+    
+
+- or clone the chatmail repo ::
+
+   git clone https://github.com/chatmail/relay
+   cd relay
+   cp example.env .env
+
+
+
+Customize and start
+^^^^^^^^^^^^^^^^^^^
+
+1. All local customizations (data paths, extra volumes, config mounts) go in
+   ``docker-compose.override.yaml``, which Compose merges automatically with
+   the base file. By default, all data is stored in docker volumes, you will
+   likely want to at least create and configure the mail storage location. Copy
+   the example to get started::
+
+       cp docker/docker-compose.override.yaml.example docker-compose.override.yaml
+       # and edit docker-compose.override.yaml
+
+
+2. Configure the ``.env`` file. Only ``MAIL_DOMAIN`` is required, the domain
+   name of the future server.
+
+   The container generates a ``chatmail.ini`` with defaults from
+   ``MAIL_DOMAIN`` on first start. To customize chatmail settings, mount
+   your own ``chatmail.ini`` instead (see `Custom chatmail.ini`_ below).
+
+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.
+
+
+Managing the server
+-------------------
+
+Use ``docker exec`` to run cmdeploy commands inside the container::
+
+    # Show required DNS records
+    docker exec chatmail /opt/cmdeploy/bin/cmdeploy dns --ssh-host @local
+
+    # Check server status
+    docker exec chatmail /opt/cmdeploy/bin/cmdeploy status --ssh-host @local
+
+    # Run benchmarks (can also run from any machine with cmdeploy installed)
+    docker exec chatmail /opt/cmdeploy/bin/cmdeploy bench chat.example.org
+
+
+Customization
+-------------
+
+Custom 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
+^^^^^^^^^^^^^^^^^^^
+
+There are two configuration modes:
+
+**Simple (default):** Set ``MAIL_DOMAIN`` in ``.env``. The container
+auto-generates ``chatmail.ini`` with defaults on first start. This is
+sufficient for most deployments.
+
+**Advanced:** Generate a ``chatmail.ini``, edit it, and mount it into
+the container. This gives you full control over all chatmail settings.
+
+1. Extract the generated config from a running container::
+
+       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
+
+
+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/chatmail-dkimkeys data/chatmail-acme data/chatmail
+
+       # DKIM keys
+       cp -a /etc/dkimkeys/* data/chatmail-dkimkeys/
+
+       # ACME certificates and account
+       rsync -a /var/lib/acme/ data/chatmail-acme/
+
+       # Mail data
+       rsync -a /home/ data/chatmail/
+
+   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 compose build chatmail
+
+The build bakes all binaries, Python packages, and the install stage
+into the image. After building, only ``docker-compose.yaml`` and ``.env``
+are needed to run the container.
+
+You can transfer a locally built image to your server directly (pigz is parallel `gzip` which can be used instead as well) ::
+
+    docker 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

@@ -80,6 +80,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
 ----------------------
 

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

docker-compose.override.yaml.example

@@ -0,0 +1,33 @@
+# Local overrides — copy to docker-compose.override.yaml in the repo root.
+# Compose automatically merges this with docker-compose.yaml.
+#
+#   cp docker/docker-compose.override.yaml.example docker-compose.override.yaml
+#
+# Volumes listed here are APPENDED to the base file's volumes.
+# Scalar values (environment, image, etc.) are REPLACED.
+services:
+  chatmail:
+    volumes:
+      ## Data paths — bind-mount to host directories for easy access/backup.
+      ## Uncomment and adjust paths as needed. These override the named
+      ## volumes in the base docker-compose.yaml.
+      # - ./data/chatmail:/home/vmail
+      # - ./data/chatmail-dkimkeys:/etc/dkimkeys
+      # - ./data/chatmail-acme:/var/lib/acme
+
+      ## Or mount data from an existing bare-metal install.
+      ## Note: DKIM key ownership is fixed automatically on startup
+      ## (the host's opendkim UID may differ from the container's).
+      # - /home/vmail:/home/vmail
+      # - /etc/dkimkeys:/etc/dkimkeys
+      # - /var/lib/acme:/var/lib/acme
+
+      ## Mount your own chatmail.ini (skips auto-generation):
+      # - ./chatmail.ini:/etc/chatmail/chatmail.ini
+
+      ## Custom website:
+      # - ./custom/www:/opt/chatmail-www
+
+      ## Debug — mount scripts from the repo for live editing:
+      # - ./docker/files/setup_chatmail_docker.sh:/setup_chatmail_docker.sh
+      # - ./docker/files/entrypoint.sh:/entrypoint.sh

docker-compose.yaml

@@ -0,0 +1,51 @@
+# Base compose file — do not edit. Put customizations (data paths, extra
+# volumes, env overrides) in docker-compose.override.yaml instead.
+# See docker/docker-compose.override.yaml.example for a starting point.
+#
+# Security note: this container uses network_mode:host (chatmail needs many
+# ports: 25, 53, 80, 143, 443, 465, 587, 993, 3340, 8443) and cgroup:host
+# (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 only
+    # privileged: true    # compose v1 (not tested)
+    tty: true # required for logs
+    tmpfs: # required for systemd
+      - /tmp
+      - /run
+      - /run/lock
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    environment:
+      MAIL_DOMAIN: $MAIL_DOMAIN
+      CMDEPLOY_STAGES: ${CMDEPLOY_STAGES:-}
+      CHATMAIL_NOSYSCTL: ${CHATMAIL_NOSYSCTL:-True}
+      CHATMAIL_NOPORTCHECK: ${CHATMAIL_NOPORTCHECK:-True}
+      CHATMAIL_NOACME: ${CHATMAIL_NOACME:-}
+    network_mode: "host"
+    volumes:
+      ## system (required)
+      - /sys/fs/cgroup:/sys/fs/cgroup:rw
+      ## data (defaults — override in docker-compose.override.yaml)
+      - chatmail-data:/home/vmail
+      - chatmail-dkimkeys:/etc/dkimkeys
+      - chatmail-acme:/var/lib/acme
+
+volumes:
+  chatmail-data:
+  chatmail-dkimkeys:
+  chatmail-acme:

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 --short HEAD)
+exec docker compose build "$@"

docker/chatmail_relay.dockerfile

@@ -0,0 +1,105 @@
+FROM jrei/systemd-debian:12 AS base
+
+ENV LANG=en_US.UTF-8
+
+RUN 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 && \
+    apt-get install -y \
+        ca-certificates && \
+    DEBIAN_FRONTEND=noninteractive \
+    TZ=UTC \
+    apt-get install -y tzdata && \
+    apt-get install -y locales && \
+    sed -i -e "s/# $LANG.*/$LANG UTF-8/" /etc/locale.gen && \
+    dpkg-reconfigure --frontend=noninteractive locales && \
+    update-locale LANG=$LANG \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN apt-get update && \
+    apt-get install -y \
+        git \
+        python3 \
+        python3-venv \
+        python3-virtualenv \
+        gcc \
+        python3-dev \
+        opendkim \
+        opendkim-tools \
+        curl \
+        rsync \
+        unbound \
+        unbound-anchor \
+        dnsutils \
+        postfix \
+        acl \
+        nginx \
+        libnginx-mod-stream \
+        fcgiwrap \
+        cron \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- 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 . /opt/chatmail/
+WORKDIR /opt/chatmail
+
+RUN printf '[params]\nmail_domain = build.local\n' > /tmp/chatmail.ini
+
+# Dummy git repo init: .git/ is excluded from the build context (.dockerignore)
+# but setuptools calls `git ls-files` when building the sdist.
+RUN git init -q && \
+    python3 -m venv /opt/cmdeploy && \
+    /opt/cmdeploy/bin/pip install --no-cache-dir \
+        -e chatmaild/ -e cmdeploy/
+
+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/
+
+RUN 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.
+ARG GIT_HASH=unknown
+RUN echo "$GIT_HASH" > /etc/chatmail-image-version && \
+    echo "$GIT_HASH" > /etc/chatmail-version
+# --- End build-time install ---
+
+ENV CHATMAIL_INI=/etc/chatmail/chatmail.ini
+ENV PATH="/opt/cmdeploy/bin:${PATH}"
+RUN ln -s /etc/chatmail/chatmail.ini /opt/chatmail/chatmail.ini
+
+ARG SETUP_CHATMAIL_SERVICE_PATH=/lib/systemd/system/setup_chatmail.service
+COPY ./docker/files/setup_chatmail.service "$SETUP_CHATMAIL_SERVICE_PATH"
+RUN ln -sf "$SETUP_CHATMAIL_SERVICE_PATH" "/etc/systemd/system/multi-user.target.wants/setup_chatmail.service"
+
+# Remove default nginx site config at build time (not in entrypoint)
+RUN rm -f /etc/nginx/sites-enabled/default
+
+COPY --chmod=555 ./docker/files/setup_chatmail_docker.sh /setup_chatmail_docker.sh
+COPY --chmod=555 ./docker/files/entrypoint.sh /entrypoint.sh
+
+# Certificate monitoring as a proper systemd timer (not a background process)
+COPY --chmod=555 ./docker/files/chatmail-certmon.sh /chatmail-certmon.sh
+COPY ./docker/files/chatmail-certmon.service /lib/systemd/system/chatmail-certmon.service
+COPY ./docker/files/chatmail-certmon.timer /lib/systemd/system/chatmail-certmon.timer
+RUN ln -sf /lib/systemd/system/chatmail-certmon.timer /etc/systemd/system/timers.target.wants/chatmail-certmon.timer
+
+HEALTHCHECK --interval=60s --timeout=10s --retries=3 \
+  CMD systemctl is-active dovecot postfix nginx unbound opendkim filtermail doveauth chatmail-metadata || exit 1
+
+STOPSIGNAL SIGRTMIN+3
+
+ENTRYPOINT ["/entrypoint.sh"]
+
+CMD [   "--default-standard-output=journal+console", \
+        "--default-standard-error=journal+console" ]
+

docker/docker-compose-traefik.yaml

@@ -0,0 +1,116 @@
+# Traefik reverse proxy + cert manager for chatmail.
+# Use this instead of docker-compose.yaml when Traefik manages TLS certificates.
+#
+# Required .env vars:
+#   MAIL_DOMAIN=chat.example.com
+#   ACME_EMAIL=admin@example.com
+#
+# Usage:
+#   cp docker/example-traefik.env .env
+#   docker compose -f docker/docker-compose-traefik.yaml build
+#   docker compose -f docker/docker-compose-traefik.yaml up -d
+
+services:
+  chatmail:
+    build:
+      context: ../
+      dockerfile: docker/chatmail_relay.dockerfile
+    image: chatmail-relay:latest
+    restart: unless-stopped
+    container_name: chatmail
+    depends_on:
+      traefik-certs-dumper:
+        condition: service_started
+    cgroup: host
+    tty: true
+    tmpfs:
+      - /tmp
+      - /run
+      - /run/lock
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    environment:
+      MAIL_DOMAIN: $MAIL_DOMAIN
+      CMDEPLOY_STAGES: ${CMDEPLOY_STAGES:-}
+      CHATMAIL_NOACME: "true"
+      PATH_TO_SSL: /var/lib/acme/live/${MAIL_DOMAIN}
+    ports:
+      - "25:25"
+      - "143:143"
+      - "465:465"
+      - "587:587"
+      - "993:993"
+    volumes:
+      - /sys/fs/cgroup:/sys/fs/cgroup:rw
+      - chatmail-data:/home
+      - chatmail-dkimkeys:/etc/dkimkeys
+      - traefik-certs:/var/lib/acme/live:ro
+
+    labels:
+      - traefik.enable=true
+      - traefik.http.services.chatmail.loadbalancer.server.scheme=https
+      - traefik.http.services.chatmail.loadbalancer.server.port=443
+      - traefik.http.services.chatmail.loadbalancer.serverstransport=insecure@file
+      - traefik.http.routers.chatmail.rule=Host(`${MAIL_DOMAIN}`) || Host(`mta-sts.${MAIL_DOMAIN}`) || Host(`www.${MAIL_DOMAIN}`)
+      - traefik.http.routers.chatmail.tls=true
+      - traefik.http.routers.chatmail.tls.certresolver=letsEncrypt
+
+  traefik:
+    image: traefik:v3.3
+    container_name: traefik
+    restart: unless-stopped
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    command:
+      - "--configFile=/config.yaml"
+      - "--certificatesresolvers.letsEncrypt.acme.email=${ACME_EMAIL}"
+    network_mode: host
+    depends_on:
+      traefik-init:
+        condition: service_completed_successfully
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./traefik/config.yaml:/config.yaml:ro
+      - traefik-data:/data
+      - ./traefik/dynamic-configs:/dynamic/conf:ro
+
+  traefik-init:
+    image: alpine:latest
+    restart: "no"
+    entrypoint: sh -c 'touch /data/acme.json && chmod 600 /data/acme.json'
+    volumes:
+      - traefik-data:/data
+
+  traefik-certs-dumper:
+    image: ldez/traefik-certs-dumper:v2.10.0
+    restart: unless-stopped
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    depends_on:
+      - traefik
+    entrypoint: sh -c '
+      apk add openssl
+      && while ! [ -e /data/acme.json ] || ! [ "$$(jq ".[] | .Certificates | length" /data/acme.json | jq -s "add")" != "0" ]; do
+        sleep 1
+      ; done
+      && traefik-certs-dumper file --version v3 --watch --domain-subdir=true
+        --source /data/acme.json --dest /certs --post-hook "sh /post-hook.sh"'
+    volumes:
+      - traefik-data:/data:ro
+      - traefik-certs:/certs
+      - ./traefik/post-hook.sh:/post-hook.sh:ro
+
+volumes:
+  chatmail-data:
+  chatmail-dkimkeys:
+  traefik-data:
+  traefik-certs:

docker/example-traefik.env

@@ -0,0 +1,5 @@
+MAIL_DOMAIN="chat.example.com"
+ACME_EMAIL="admin@example.com"
+
+# CMDEPLOY_STAGES - default: "configure,activate". Set to "install,configure,activate" to force full reinstall.
+# CMDEPLOY_STAGES="configure,activate"

docker/files/chatmail-certmon.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=Check TLS certificate changes and reload services
+After=setup_chatmail.service
+
+[Service]
+Type=oneshot
+ExecStart=/bin/bash /chatmail-certmon.sh
+PassEnvironment=MAIL_DOMAIN PATH_TO_SSL

docker/files/chatmail-certmon.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Check if TLS certificates have changed and reload services if so.
+# Called by chatmail-certmon.timer (systemd timer, default every 60s).
+set -eo pipefail
+
+PATH_TO_SSL="${PATH_TO_SSL:-/var/lib/acme/live/${MAIL_DOMAIN}}"
+HASH_FILE="/run/chatmail-certmon.hash"
+
+if [ ! -d "$PATH_TO_SSL" ]; then
+    exit 0
+fi
+
+current_hash=$(find "$PATH_TO_SSL" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}')
+previous_hash=""
+if [ -f "$HASH_FILE" ]; then
+    previous_hash=$(cat "$HASH_FILE")
+fi
+
+if [ -n "$current_hash" ] && [ "$current_hash" != "$previous_hash" ]; then
+    echo "[INFO] Certificate hash changed, reloading nginx, dovecot and postfix."
+    echo "$current_hash" > "$HASH_FILE"
+    # On first run (no previous hash), don't reload — services may not be up yet
+    if [ -n "$previous_hash" ]; then
+        systemctl reload nginx.service
+        systemctl reload dovecot.service
+        systemctl reload postfix.service
+    fi
+fi

docker/files/chatmail-certmon.timer

@@ -0,0 +1,9 @@
+[Unit]
+Description=Periodically check TLS certificate changes
+
+[Timer]
+OnBootSec=120
+OnUnitActiveSec=60
+
+[Install]
+WantedBy=timers.target

docker/files/entrypoint.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+set -eo pipefail
+
+SETUP_CHATMAIL_SERVICE_PATH="${SETUP_CHATMAIL_SERVICE_PATH:-/lib/systemd/system/setup_chatmail.service}"
+
+# Whitelist only the env vars needed by setup_chatmail_docker.sh.
+# Forwarding all env vars (via printenv) would leak Docker internals,
+# orchestrator secrets, and other unrelated variables into systemd.
+env_vars="MAIL_DOMAIN CMDEPLOY_STAGES CHATMAIL_INI CHATMAIL_NOSYSCTL CHATMAIL_NOPORTCHECK CHATMAIL_NOACME PATH_TO_SSL PATH"
+sed -i "s|<envs_list>|$env_vars|g" "$SETUP_CHATMAIL_SERVICE_PATH"
+
+exec /lib/systemd/systemd "$@"

docker/files/setup_chatmail.service

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

docker/files/setup_chatmail_docker.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+set -euo pipefail
+export CHATMAIL_INI="${CHATMAIL_INI:-/etc/chatmail/chatmail.ini}"
+
+CMDEPLOY=/opt/cmdeploy/bin/cmdeploy
+
+if [ -z "$MAIL_DOMAIN" ]; then
+    echo "ERROR: Environment variable 'MAIL_DOMAIN' must be set!" >&2
+    exit 1
+fi
+
+### MAIN
+
+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
+
+# Journald: forward to console for docker logs
+grep -q '^ForwardToConsole=yes' /etc/systemd/journald.conf \
+    || echo "ForwardToConsole=yes" >> /etc/systemd/journald.conf
+systemctl restart systemd-journald
+
+# Create chatmail.ini (skips if file already exists, e.g. volume-mounted)
+mkdir -p "$(dirname "$CHATMAIL_INI")"
+if [ ! -f "$CHATMAIL_INI" ]; then
+    $CMDEPLOY init --config "$CHATMAIL_INI" "$MAIL_DOMAIN"
+fi
+
+# --- Deploy fingerprint: skip cmdeploy run if nothing changed ---
+# On restart with identical image+config, systemd already brings up all
+# enabled services — the full cmdeploy run is redundant (~30s saved).
+# The install stage runs at image build time (Dockerfile), so 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}"
+    $CMDEPLOY run --config "$CHATMAIL_INI" --ssh-host @local
+    echo "$current_fp" > "$FINGERPRINT_FILE"
+fi

docker/traefik/config.yaml

@@ -0,0 +1,30 @@
+log:
+  level: INFO
+
+entryPoints:
+  web:
+    address: ":80"
+    http:
+      redirections:
+        entryPoint:
+          to: websecure
+          permanent: true
+  websecure:
+    address: ":443"
+
+providers:
+  docker:
+    endpoint: "unix:///var/run/docker.sock"
+    exposedByDefault: false
+  file:
+    directory: /dynamic/conf
+    watch: true
+
+certificatesResolvers:
+  letsEncrypt:
+    acme:
+      storage: /data/acme.json
+      caServer: "https://acme-v02.api.letsencrypt.org/directory"
+      tlschallenge: true
+      httpChallenge:
+        entryPoint: web

docker/traefik/dynamic-configs/insecure.yaml

@@ -0,0 +1,4 @@
+http:
+  serversTransports:
+    insecure:
+      insecureSkipVerify: true

docker/traefik/post-hook.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Post-hook for traefik-certs-dumper: create symlinks from Traefik's
+# cert dump format to the paths chatmail expects (fullchain, privkey).
+CERTS_DIR="${CERTS_DIR:-/certs}"
+
+for dir in "$CERTS_DIR"/*/; do
+    [ -d "$dir" ] || continue
+    cd "$dir"
+    [ -f "certificate.crt" ] && ln -sf certificate.crt fullchain
+    [ -f "privatekey.key" ] && ln -sf privatekey.key privkey
+    cd - > /dev/null
+done

env.example

@@ -0,0 +1,7 @@
+MAIL_DOMAIN="chat.example.com"
+
+# CMDEPLOY_STAGES - default: "configure,activate". Set to "install,configure,activate" to force full reinstall.
+# CMDEPLOY_STAGES="configure,activate"
+
+# Skip acmetool when using an external certificate manager (e.g. Traefik, Caddy).
+# CHATMAIL_NOACME="True"