Installation

Mailyard is a single binary. It embeds the console frontend, this documentation, and its database migrations, so a deployment is one container plus a PostgreSQL.

The delivery queue lives in PostgreSQL and the worker runs inside the server process, so mailyard serve is the whole system. When one process is no longer enough, several run against the same database off the same binary and the same config. See Scaling out .

Docker Compose

services:
    postgres:
        image: postgres:17-alpine
        environment:
            POSTGRES_USER: mailyard
            POSTGRES_PASSWORD: change-me
            POSTGRES_DB: mailyard
        volumes:
            - pgdata:/var/lib/postgresql/data
        healthcheck:
            test: [ "CMD-SHELL", "pg_isready -U mailyard -d mailyard" ]
            interval: 5s
            retries: 10
        restart: unless-stopped

    mailyard:
        image: mailyard:latest
        # --init applies pending migrations. See the note below.
        command: [ "serve", "--init" ]
        depends_on:
            postgres:
                condition: service_healthy
        ports:
            - "3000:3000"
            # Only if you enable the SMTP listeners.
            - "587:587"
            - "25:25"
        environment:
            MAILYARD_DATABASE_DSN: postgres://mailyard:change-me@postgres:5432/mailyard?sslmode=disable
            # Both REQUIRED, each from `openssl rand -hex 32`. Mailyard refuses
            # to start until they are set. The encryption key is what seals
            # stored secrets - losing it means losing them.
            MAILYARD_AUTH_JWT_SECRET: ""
            MAILYARD_DATABASE_CRYPTO_ENCRYPTION_KEY: ""
            MAILYARD_AUTH_LOCAL_ENABLED: "true"
            MAILYARD_AUTH_LOCAL_EMAIL: admin@example.com
            MAILYARD_SERVER_PUBLIC_URL: https://mail.example.com
        healthcheck:
            test: [ "CMD", "wget", "-qO-", "http://localhost:3000/healthz" ]
            interval: 30s
            start_period: 15s
            retries: 3
        restart: unless-stopped

volumes:
    pgdata:

docker compose up -d

MAILYARD_SERVER_PUBLIC_URL is worth setting before the first send rather than after. Tracking links, hosted unsubscribe pages and invitation mail are all absolute URLs built from it, and campaigns refuse to start without it.

On the first start the bootstrap admin password is printed to stderr once — read it out of the container log before doing anything else:

docker compose logs mailyard | grep -i password

The console is then at http://localhost:3000/app.

TLS

The configuration file answers one question about TLS: whether each listener terminates it. It says nothing about which certificate — that is chosen in the console and stored in the database, so every node serves the same one and a replacement needs no restart.

The HTTP default is off because the common deployment puts a reverse proxy in front that terminates TLS and speaks plain HTTP upstream. Turn it on to serve HTTPS directly.

Terminating TLS in Mailyard

Bind 443 and switch the listener on. There is nothing else to configure: with nothing assigned, a self-signed pair is generated on first use and shared by every node, so the console is reachable immediately over HTTPS with a browser warning.

services:
    mailyard:
        ports:
            - "443:443"
            - "587:587"
            - "25:25"
        environment:
            MAILYARD_SERVER_ADDR: ":443"
            MAILYARD_SERVER_TLS_ENABLED: "true"
            MAILYARD_SERVER_PUBLIC_URL: https://mail.example.com

Then sign in and replace that pair under Administration → Certificates: upload one you already have, generate one signed by an internal CA, or order one from Let’s Encrypt. See Certificates .

Ordering from Let’s Encrypt

ACME is turned on in the console under Administration → Certificates, not in the config file — see Certificates . The order is:

1. Make sure the CA can reach this installation, which is one of two ways:
   • tls-alpn-01, when the TLS handshake on port 443 reaches Mailyard — bound directly with MAILYARD_SERVER_TLS_ENABLED: "true" as above, or through a TCP-passthrough proxy, which preserves ALPN. The handshake is the validation, and port 80 is never used.
   • http-01, behind a proxy that terminates TLS, where the handshake never gets to us. Set MAILYARD_ACME_CHALLENGE_ADDR (empty by default) and have the proxy forward /.well-known/acme-challenge/* for the mail hostname to it. The port is bound at startup whether ACME is on or not, so this is the one step that needs a restart. The proxy route, with a Caddy example, is in Certificates .
2. Sign in, open Administration → Certificates → Settings, and set acme_enabled, then acme_hosts — one hostname per line. Optionally acme_email, where the CA sends expiry warnings.
3. Press Order beside a host. It is synchronous, so a refusal comes back with the CA’s own words. Nothing else needs a restart: the settings are read fresh on every handshake and every order.

A hostname that is not in the ACME list falls through to the self-signed pair rather than failing the handshake, so a mail listener answering under a name the certificate does not cover still offers working STARTTLS.

Ports

443, 587, 25 and 80 are all privileged. Docker sets net.ipv4.ip_unprivileged_port_start=0 inside containers, so the published image binds them as uid 1000 with no extra configuration. Kubernetes does not — grant NET_BIND_SERVICE. Elsewhere, bind a high port and map the low one to it.

Scaling out

Run more replicas of the same container against the same database. Every node runs the worker, and delivery is claimed with a conditional UPDATE, so two nodes cannot send the same message twice.

Two things to know before you do:

• Rate limits are per process. The HTTP limiters are in-process fixed windows, so three replicas mean three times the configured ceiling. Size them accordingly, or apply the limit at a shared proxy instead.
• Scheduled jobs run on every node. There is no leader election. The jobs are written to be idempotent and safe to run concurrently.

Build from Source

Prerequisites

• Go 1.27+
• PostgreSQL 15+
• Node.js 18+, to build the console
• go-task 3+, which runs the build steps (go install github.com/go-task/task/v3/cmd/task@latest)

PostgreSQL 15 is a hard floor, not a preference: the schema uses UNIQUE NULLS NOT DISTINCT, which 14 cannot parse, so migrations fail outright on an older server rather than degrading.

Steps

git clone https://github.com/yousysadmin/mailyard.git
cd mailyard

# Builds the console into web/dist, the docs into docs/dist, then the binary.
task build

# --init applies the schema. Exactly one node in a fleet carries it;
# a single-node install always does.
./bin/mailyard serve --init

task build is what produces a binary with the console and documentation inside it. A bare go build ./... compiles and is fine for development, but the resulting binary serves no console and no docs, because the embedded directories are empty.

Configuration comes from ./mailyard.yaml (see ../../../examples/mailyard.yaml.example) or from the environment. See Configuration .

Health Checks

# Liveness - the process is up.
curl http://localhost:3000/healthz

# Readiness - the process is up and the database answers.
curl http://localhost:3000/readyz

Use /healthz for a restart probe and /readyz to gate traffic. Pointing a restart probe at /readyz means a brief database blip restarts every node at once, which turns a recoverable outage into a longer one.