Webstar/LibrePortal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
LibrePortal/containers/stalwart/stalwart.config
librelad 7ed1cddd5c stalwart: answer the setup wizard instead of handing it to the user 
A new Stalwart drops you into a five-screen wizard — hostname, domain,
storage backend, directory, logging, DNS — before it will do anything.
LibrePortal already knows the two answers that matter and the rest have
sane defaults, so asking is asking a question we can answer ourselves.

v0.16 exposes those wizard fields as a `Bootstrap` singleton, so the whole
thing is one `update` applied through the Stalwart CLI. The CLI is not in
the server image (upstream split it into its own repo), but it publishes a
multi-arch container, so we borrow the server's network namespace and run
it there — nothing installed on the host, nothing to clean up, arm64 works.

Setup now also:

- generates DKIM keys (Ed25519 + RSA) with rotation left switched on, and
  requests a TLS certificate. That last one is easy to miss: Traefik only
  fronts the admin port, so 25/465/587/993 never see its certificate and
  clients would hit a self-signed one on 993.
- creates postmaster@<domain>. The generated zone points DMARC and TLS-RPT
  reports there and nothing was creating it, so those reports bounced.
- prints the record set read back from the server rather than composed
  here, so it includes the real DKIM public keys, MTA-STS, TLS-RPT and the
  SRV records clients autoconfigure from. This hook used to tell the user
  to go and fetch DKIM themselves; by that point the keys exist.

Optionally hands DNS to a provider API (Cloudflare/DigitalOcean/DeSEC),
which keeps the whole record set in sync and makes DKIM rotation safe to
leave on. Off by default: the token can write to your zone and lives in
the mail server's database.

Re-running is safe — provisioning is skipped once config.json exists, and
the plans use upsert so they reconcile rather than duplicate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-18 05:05:03 +01:00

145 lines
8.6 KiB
Plaintext
Raw Blame History

#
# =============================================================================
# GENERAL CONFIGURATION
# =============================================================================
# APP_NAME = name of application for use in scripts
# COMPOSE_FILE = default for no app_name in docker-compose file name, app if there is
# BACKUP = if true, include this application in backup operations
# UPDATE_TYPE = auto: new image builds are applied automatically (a recovery snapshot is taken first), manual: only when you press Update
# VERSION = the Stalwart release line this install tracks; drives the image tag.
# The two settings do different jobs and are safe together:
# UPDATE_TYPE=auto picks up REBUILDS of the version below (security/bug
# patches) — snapshot, pull, recreate. Your data volume is untouched;
# nothing is reinstalled.
# Changing VERSION is how you move BETWEEN releases (v0.16 -> v0.17).
# So patches land on their own, while a version jump stays a decision you
# make — which matters while Stalwart is pre-1.0 and still settling its
# storage schema.
# HEALTHCHECK = if true, default docker health checks for that container will be enabled
# AUTHELIA = if true, use Authelia authentication, if false turned off.
# HEADSCALE = options : false, local, remote (see general config). e.g false or local,remote
#
CFG_STALWART_APP_NAME=stalwart
CFG_STALWART_BACKUP=true
# Mail is the one app where a "live" snapshot is a real risk: the message store
# is being written continuously, so a copy taken mid-write can land mid-transaction.
# stop-snapshot-start costs seconds of queued delivery (senders retry — that is
# what SMTP does) and buys a consistent store.
CFG_STALWART_BACKUP_STRATEGY=stop-snapshot-start
CFG_STALWART_UPDATE_TYPE=auto
CFG_STALWART_VERSION=v0.16
CFG_STALWART_COMPOSE_FILE=default
CFG_STALWART_HEALTHCHECK=true
CFG_STALWART_AUTHELIA=false
CFG_STALWART_HEADSCALE=false
#
# =============================================================================
# METADATA
# =============================================================================
# CATEGORY = application category for grouping
# TITLE = display name for the application
# DESCRIPTION = short description of the application
# LONG_DESCRIPTION = detailed description of the application
# URL = source repository or documentation URL
# ACTIONS = available actions for this application
#
CFG_STALWART_CATEGORY="communication"
CFG_STALWART_TITLE="Stalwart"
CFG_STALWART_DESCRIPTION="Mail Server"
CFG_STALWART_LONG_DESCRIPTION="Stalwart is an all-in-one mail and collaboration server — SMTP, IMAP, POP3 and JMAP plus calendars and contacts, in a single container with a built-in admin interface and spam filtering."
CFG_STALWART_URL="https://github.com/stalwartlabs/stalwart"
CFG_STALWART_ACTIONS="configure|install|restart|shutdown|uninstall"
#
# =============================================================================
# NETWORK CONFIGURATION
# =============================================================================
# DOMAIN = number of domain from the general config, useful when using multiple domains
# WHITELIST = if true only allow whitelisted ips (see general config), if false allow all
#
CFG_STALWART_DOMAIN=1
CFG_STALWART_WHITELIST=false
CFG_STALWART_NETWORK=default
#
# =============================================================================
# PORT CONFIGURATION
# =============================================================================
# PORT_ = port configuration: app|name|external:internal|access|protocol|login|traefik|webui|description|paths|subdomain
# - app: application name
# - name: service identifier (webui, dns, ssh, etc.)
# - external:internal: port mapping (external can be 'random' for auto-allocation)
# - access: 'public' (internet accessible), 'private' (local network only), 'disabled' (not running)
# - protocol: 'tcp' or 'udp'
# - login: if true, this port requires basic-auth via Traefik (only meaningful when traefik=true)
# - traefik: if true, Traefik handles this port (reverse proxy)
# - webui: if true, this port serves the main web interface
# - description: human-readable description of the service
#
# MAIL PORTS ARE FIXED, NOT RANDOM. Every other app can take a random external
# port because only a browser (via Traefik) reaches it. Mail is different: other
# mail servers on the internet connect to port 25 by number, and mail clients
# expect 465/587/993 — a randomised external port silently makes the server
# unreachable. Only the admin UI gets a random port, because that one IS just a
# browser behind Traefik.
CFG_STALWART_PORT_1="stalwart-service|webui|random:8080|public|tcp|false|true|true|Admin Interface||mail"
CFG_STALWART_PORT_2="stalwart-service|smtp|25:25|public|tcp|false|false|false|SMTP (server-to-server mail delivery)|"
CFG_STALWART_PORT_3="stalwart-service|submissions|465:465|public|tcp|false|false|false|Mail submission (implicit TLS)|"
CFG_STALWART_PORT_4="stalwart-service|submission|587:587|public|tcp|false|false|false|Mail submission (STARTTLS)|"
CFG_STALWART_PORT_5="stalwart-service|imaps|993:993|public|tcp|false|false|false|IMAP (implicit TLS)|"
CFG_STALWART_PORT_6="stalwart-service|imap|143:143|disabled|tcp|false|false|false|IMAP (STARTTLS) — enable only if a client needs it|"
CFG_STALWART_PORT_7="stalwart-service|pop3s|995:995|disabled|tcp|false|false|false|POP3 (implicit TLS) — off by default, IMAP is preferred|"
CFG_STALWART_PORT_8="stalwart-service|sieve|4190:4190|disabled|tcp|false|false|false|ManageSieve (client-managed mail filters)|"
CFG_STALWART_PORT_9="stalwart-service|jmap|443:443|disabled|tcp|false|false|false|HTTPS/JMAP direct — leave disabled when Traefik fronts the UI|"
# AUTH_PROFILE = capability tier for the WebUI auth tools (single_password | user_password | multi_user)
# The password reaches the container through a compose environment variable, so
# if you replace the generated one by hand keep it alphanumeric: docker compose
# interpolates `$` and YAML treats ` #` as a comment, either of which would
# silently mangle the value. The generator only emits letters and digits.
CFG_STALWART_AUTH_PROFILE=user_password
CFG_STALWART_ADMIN_USER=admin
CFG_STALWART_ADMIN_PASSWORD=RANDOMIZEDPASSWORD1
#
# =============================================================================
# AUTOMATIC SETUP
# =============================================================================
# Out of the box Stalwart opens a five-screen setup wizard on first sign-in and
# waits for a human. LibrePortal already knows the answers that matter — the
# hostname and the domain — so the installer fills the wizard in instead, and
# the user's first sight of Stalwart is a configured mail server.
#
# CLI_VERSION = the version of the Stalwart CLI used to apply that setup.
# Pinned, not ':latest', for the same reason the server image is: this writes
# configuration, so an unattended jump to a new CLI is not something to
# discover during an install. The CLI is a separate upstream project from the
# server and is NOT included in the server image, which is why it is a
# container of its own rather than something bundled.
CFG_STALWART_CLI_VERSION=1.0.12
#
# FIRST_MAILBOX = local part of one real mailbox created during setup.
# Setup leaves you with admin@<domain>, which is an administrator account
# rather than somewhere to read mail. 'postmaster' is the default for a
# concrete reason: the generated zone file points DMARC and TLS-RPT reports at
# postmaster@<domain>, and if nothing creates it those reports bounce.
# Set empty to skip creating it.
CFG_STALWART_FIRST_MAILBOX=postmaster
CFG_STALWART_FIRST_MAILBOX_PASSWORD=RANDOMIZEDPASSWORD2
#
# DNS_PROVIDER = 'manual', or a provider name to let Stalwart publish DNS itself.
# On 'manual' the installer prints the full record set — including the real
# DKIM public keys — for you to paste at your registrar.
# Given a provider, Stalwart writes MX, SPF, DKIM, DMARC, MTA-STS, TLS-RPT,
# SRV and CAA into the zone through the provider's API and keeps them in sync.
# That also makes DKIM key rotation safe to leave switched on, since the server
# republishes the records itself — hand-managed DKIM keys are, in practice,
# keys nobody ever rotates.
#
# Wired up here: Cloudflare, DigitalOcean, DeSEC (token-only providers).
# Route 53 and Google Cloud DNS need more than a token — set those up in the
# admin console instead.
#
# The trade: the token is stored in the mail server's database and can write to
# your zone, so compromising this box means compromising your DNS. Scope the
# token to this one zone if your provider allows it.
CFG_STALWART_DNS_PROVIDER=manual
CFG_STALWART_DNS_API_TOKEN=
Reference in New Issue View Git Blame Copy Permalink