mxhop

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: trueThe 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: 30sLonger than the 25-second grace mxhop gives its own sessions, so a stop finishes rather than being killed in the middle of it.
init: trueA 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.