Install · container
Run it in a container
The image is FROM scratch. Not Alpine, not distroless — nothing at all except the binary and a CA bundle. About 8 MB, no shell, no package manager, no libc, and therefore nothing inside it that can have a CVE next month.
The whole of it
mkdir -p /srv/mxhop/config /srv/mxhop/spool
$EDITOR /srv/mxhop/config/mxhop.toml
docker run -d --name mxhop \
--restart unless-stopped \
-p 25:2525 \
-v /srv/mxhop/config:/etc/mxhop:ro \
-v /srv/mxhop/spool:/var/lib/mxhop/spool \
ghcr.io/metronom72/mxhop:0.3.0
Port 25 outside maps to 2525 inside, so nothing in the container is privileged. Set listen = "0.0.0.0:2525" in the config to match.
The spool volume is not optional. Without it, a container replacement throws away every message still waiting for a destination that was briefly down. The spool is the only state mxhop has, and it is mail somebody is waiting for.
There is no shell to get into
Which changes how you work with it. docker exec … sh fails, because there is no sh. The binary is the only executable in the image, and it is also the entire operator interface:
# validate the mounted config docker exec mxhop /mxhop check /etc/mxhop/mxhop.toml: ok — mx.example.com on 0.0.0.0:2525, 4 aliases for example.com, SRS at example.com (1 key, 7 day window), STARTTLS, SPF/DKIM/DMARC checked, and a p=reject failure refused # ask the running process how it is docker exec mxhop /mxhop health ok listener: ok spool: ok queue: 0/100000 resolver: ok
That same command is the image's HEALTHCHECK, so docker ps shows (healthy) on the strength of the process's own answer rather than a port being open.
To read the queue, read the host side of the spool mount — it is plain files, and the host has all the tools: ls /srv/mxhop/spool/queue/.
Compose
The file in the repository is the one used in production. Every line below the image is a restriction:
services: mxhop: image: ghcr.io/metronom72/mxhop:0.3.0 init: true restart: unless-stopped stop_grace_period: 30s user: "10001:10001" cap_drop: [ALL] security_opt: ["no-new-privileges:true"] read_only: true ports: ["25:2525"] volumes: - { type: bind, source: ./spool, target: /var/lib/mxhop/spool } - { type: bind, source: ./config, target: /etc/mxhop, read_only: true } healthcheck: test: ["CMD", "/mxhop", "health"] interval: 60s timeout: 10s start_period: 10s retries: 3 logging: driver: json-file options: { max-size: "10m", max-file: "5" }
| cap_drop: [ALL] | It needs no capability at all once the port mapping does the privileged part. |
| read_only: true | The root filesystem is read-only. The spool mount is the only writable path, which is all it ever writes to. |
| user: "10001:10001" | Never root, even inside. The spool directory on the host must be owned by this uid. |
| stop_grace_period: 30s | Longer than the 25-second grace mxhop gives its own sessions, so a stop finishes rather than being killed in the middle of it. |
| init: true | A real init as pid 1, so signals arrive and zombies get reaped. |
Swarm, and both architectures
A stack file ships alongside the compose file. The image is a multi-arch manifest covering linux/amd64 and linux/arm64, each built natively on its own runner rather than emulated, so the digest you pull on an ARM box is a binary actually compiled there.
docker stack deploy -c deploy/mxhop.stack.yml mxhop
docker service ps mxhop_mxhop
Pin the tag, or better, the digest. :latest on the thing that receives your mail means an unattended update can change how your mail is handled. docker buildx imagetools inspect ghcr.io/metronom72/mxhop:0.3.0 prints the digest to pin.