mirror of
https://github.com/karatektus/pl_mail.git
synced 2026-10-25 10:04:18 +00:00
Paul LütznerandClaude Opus 5.5
a8364e34d2
The stack was nine long-running containers: the web server, the database, the Mercure hub, and six of plMail's own image, one per background process. It is three now: php, worker and database, with secrets-init still running once and exiting. The worker runs `app:work`, a small supervisor keeping seven processes alive the way Docker's restart policy kept seven containers alive: the IMAP supervisor, one consumer per queue, the scheduler and the hub. A clean exit (the hourly recycle, the restart signal) comes straight back; a crash backs off from one second to thirty. Output passes through a whole line at a time, so two processes' JSON records never interleave, and SIGTERM reaches every child at once with 25s to finish. Each queue keeps a process of its own, which is the part the split was for: a consumer inside a long handler cannot take a send. And each process keeps its container's old name as APP_CONTAINER_NAME, so heartbeats, /healthz and the log filters are unchanged. The hub is the official Mercure 1.x binary, copied into the image and run as one of those processes. Not FrankenPHP's built-in hub, which is 0.24 and refuses the RFC 9068 tokens plMail has minted since v0.2.31. The worker answers to `mercure` on the network, so the Caddyfile proxy and MERCURE_URL reach it where they reached the hub container, and older compose files keep working with this image unchanged. It is configured from the application's own settings, including MERCURE_COOKIE_NAME, so a plain-HTTP install names the cookie once for both halves. A 5s shutdown grace stops it waiting on open subscriptions, which made every stop take the whole 25s. The dev override loses its per-worker blocks, one of which (worker-bulk) had been missing, so that queue ran the published image's code in development. The demo overlay runs app:work --without=imap-supervisor. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
304 lines
14 KiB
YAML
304 lines
14 KiB
YAML
# plMail — TrueNAS SCALE custom app (Apps > Discover > ⋮ > Install via YAML)
|
|
#
|
|
# TrueNAS's YAML installer does NOT support ${VAR} interpolation, so all config is
|
|
# hoisted into the x-config block below and aliased (*name) into the services.
|
|
# Edit that block; nothing below it needs touching.
|
|
#
|
|
# You do NOT need to create any directories by hand. Every bind below carries
|
|
# create_host_path, so Docker makes them on first start. Point them at a dataset
|
|
# rather than a plain directory if you want ZFS snapshots of your mail.
|
|
|
|
name: plmail
|
|
|
|
# ─────────────────────────────────────────────────────────────────────────────
|
|
# 1. REQUIRED — the only thing to configure. Everything else works as-is.
|
|
# ─────────────────────────────────────────────────────────────────────────────
|
|
x-config:
|
|
# -- Storage --
|
|
# One directory. plMail makes its own subfolders inside it — postgres,
|
|
# attachments, raw, uploads, secrets — so there is nothing to create and
|
|
# nothing else to point anywhere.
|
|
#
|
|
# This is the whole install. Back it up, or make it a dataset and snapshot
|
|
# it: the secrets subfolder holds the key every mailbox password is
|
|
# encrypted with, and without it they are gone.
|
|
path_data: &path_data /mnt/yourPool/yourDataSet/plmail
|
|
|
|
# ─────────────────────────────────────────────────────────────────────────────
|
|
# 2. OPTIONAL — every one of these works left exactly as it is.
|
|
# ─────────────────────────────────────────────────────────────────────────────
|
|
|
|
# -- Which builds you get --
|
|
# The tag on the image decides how often this install changes, and it is
|
|
# the one optional setting worth deciding on deliberately:
|
|
#
|
|
# :latest the most recent tagged release. Moves only when a version is
|
|
# released. The default, and what most installs want.
|
|
# :main every merge into the default branch, released or not. Follow
|
|
# this to run what is being worked on without waiting for a
|
|
# version to be tagged — it can break, and the changelog will
|
|
# not describe it yet.
|
|
# :0.0.14 one release, pinned. Nothing changes until you edit this.
|
|
# No leading "v" — the git tag is v0.0.14, the image tag is not.
|
|
# :0.0 the newest patch of one minor line.
|
|
# :sha-1a2b3c one commit, pinned exactly.
|
|
#
|
|
# Every service pulls on start (pull_policy: always), so a redeploy from the
|
|
# TrueNAS app page is what picks up a newer build of whichever tag is set.
|
|
# Downgrading is not supported: migrations run forward on boot, so moving
|
|
# from :main back to :latest can leave the database ahead of the code.
|
|
image: &image ghcr.io/karatektus/pl_mail:latest
|
|
http_port: &http_port 30080
|
|
|
|
# -- Public address --
|
|
# LEAVE BLANK. The setup screen asks for the public URL on first boot and
|
|
# stores it; the Mercure hub URL is then derived from it automatically
|
|
# (the hub is proxied on the same origin, at /.well-known/mercure).
|
|
# Fill these in only to pin values from the environment — anything set
|
|
# here wins over what the setup screen stored.
|
|
app_public_url: &app_public_url ""
|
|
mercure_public_url: &mercure_public_url ""
|
|
|
|
# -- Secrets --
|
|
# LEAVE THESE BLANK. All four are generated on first start into the storage
|
|
# directory above. Fill one in only if you manage secrets yourself; nothing is ever
|
|
# generated over the top of a value you supplied.
|
|
#
|
|
# app_encryption_key encrypts every mailbox password and OAuth token at rest.
|
|
# Changing it once mail accounts exist makes the app refuse to start rather
|
|
# than overwrite what it can no longer read — see CONTRIBUTING.md.
|
|
app_secret: &app_secret ""
|
|
app_encryption_key: &app_encryption_key ""
|
|
db_password: &db_password ""
|
|
mercure_jwt: &mercure_jwt ""
|
|
|
|
# Leave blank and the app assembles it from the generated db_password. Set it
|
|
# only to point plMail at a database of your own — and then the password
|
|
# inside it MUST equal db_password (an anchor cannot be spliced mid-string):
|
|
database_url: &database_url ""
|
|
|
|
# -- Web Push (browser/PWA notifications + JMAP PushSubscription) --
|
|
# Generated on first start if left blank. Rotating them invalidates every
|
|
# existing subscription; every device has to re-enable notifications.
|
|
# vapid_subject must be a mailto: or https: URL identifying you (RFC 8292).
|
|
vapid_subject: &vapid_subject "mailto:you@yourdomain.com"
|
|
vapid_public_key: &vapid_public_key ""
|
|
vapid_private_key: &vapid_private_key ""
|
|
|
|
# -- Gmail and Outlook sign-in --
|
|
# These are easier to set up from inside plMail: Admin → Integrations walks
|
|
# through it and shows you the redirect URI to paste into the provider's
|
|
# console. Anything entered there is stored in the database and wins over
|
|
# what is here, so most installs can leave this whole block alone.
|
|
google_client_id: &google_client_id ""
|
|
google_client_secret: &google_client_secret ""
|
|
gmail_pubsub_topic: &gmail_pubsub_topic "projects/your-project-id/topics/gmail-push"
|
|
# Shared secret appended to the Pub/Sub push endpoint as ?token=… — must
|
|
# match the push subscription in Google Cloud or every push is rejected.
|
|
gmail_pubsub_token: &gmail_pubsub_token ""
|
|
|
|
graph_client_id: &graph_client_id ""
|
|
graph_client_secret: &graph_client_secret ""
|
|
|
|
# ─────────────────────────────────────────────────────────────────────────────
|
|
|
|
x-app-env: &app-env
|
|
APP_ENV: prod
|
|
APP_PUBLIC_URL: *app_public_url
|
|
APP_SECRET: *app_secret
|
|
APP_ENCRYPTION_KEY: *app_encryption_key
|
|
DATABASE_URL: *database_url
|
|
POSTGRES_USER: app
|
|
POSTGRES_DB: app
|
|
# Everything plMail writes goes under the single mounted directory.
|
|
APP_STORAGE_DIR: var/data
|
|
APP_SECRETS_DIR: /app/var/data/secrets
|
|
APP_SECRETS_FILE: /app/var/data/secrets/generated.env
|
|
MESSENGER_TRANSPORT_DSN: "doctrine://default?auto_setup=0"
|
|
MERCURE_URL: "http://mercure/.well-known/mercure"
|
|
MERCURE_PUBLIC_URL: *mercure_public_url
|
|
VAPID_SUBJECT: *vapid_subject
|
|
VAPID_PUBLIC_KEY: *vapid_public_key
|
|
VAPID_PRIVATE_KEY: *vapid_private_key
|
|
MERCURE_JWT_SECRET: *mercure_jwt
|
|
GOOGLE_OAUTH_CLIENT_ID: *google_client_id
|
|
GOOGLE_OAUTH_CLIENT_SECRET: *google_client_secret
|
|
GMAIL_PUBSUB_TOPIC: *gmail_pubsub_topic
|
|
GMAIL_PUBSUB_VERIFICATION_TOKEN: *gmail_pubsub_token
|
|
MICROSOFT_OAUTH_CLIENT_ID: *graph_client_id
|
|
MICROSOFT_OAUTH_CLIENT_SECRET: *graph_client_secret
|
|
MICROSOFT_OAUTH_TENANT: common
|
|
TRUSTED_PROXIES:
|
|
|
|
services:
|
|
# Mints whatever was left blank above into the storage directory, then exits. Runs
|
|
# before everything else: Postgres reads its password when its container is
|
|
# created and cannot wait for the app to hand it one.
|
|
# Idempotent — on every later start it finds the file and does nothing.
|
|
secrets-init:
|
|
image: *image
|
|
pull_policy: always
|
|
restart: "no"
|
|
# Lays out the shared directory before anything else starts, then mints
|
|
# the secrets. Docker creates the host path as root, and Postgres runs
|
|
# as uid 999 in the 18-alpine image (uid 70 before 18) — it cannot make
|
|
# its own data directory inside a root-owned parent, which is the one
|
|
# thing "subfolders are automatic" cannot leave to the services
|
|
# themselves.
|
|
entrypoint:
|
|
- /bin/sh
|
|
- -c
|
|
- |
|
|
set -eu
|
|
mkdir -p /app/var/data/secrets \
|
|
/app/var/data/postgres \
|
|
/app/var/data/attachments \
|
|
/app/var/data/raw \
|
|
/app/var/data/uploads
|
|
chown -R 999:999 /app/var/data/postgres
|
|
# Postgres re-execs as uid 999 and must be able to traverse the
|
|
# mount root, but a TrueNAS dataset with the "Apps" preset is
|
|
# 770 apps:apps — no x-bit for uid 999. Execute-only: grants
|
|
# traversal, not the ability to list or read anything.
|
|
chmod o+x /app/var/data || setfacl -m u:999:--x /app/var/data || true
|
|
exec generate-secrets
|
|
environment:
|
|
APP_SECRETS_DIR: /app/var/data/secrets
|
|
APP_SECRET: *app_secret
|
|
APP_ENCRYPTION_KEY: *app_encryption_key
|
|
POSTGRES_PASSWORD: *db_password
|
|
MERCURE_JWT_SECRET: *mercure_jwt
|
|
volumes:
|
|
- type: bind
|
|
source: *path_data
|
|
target: /app/var/data
|
|
bind:
|
|
create_host_path: true
|
|
|
|
php:
|
|
image: *image
|
|
pull_policy: always
|
|
restart: unless-stopped
|
|
environment:
|
|
<<: *app-env
|
|
# ":80" = FrankenPHP serves plain HTTP; terminate TLS at your reverse proxy (recommended).
|
|
# For a domain forwarded straight to :443 here, set this to that hostname and re-add the 443 ports.
|
|
SERVER_NAME: ":80"
|
|
MAILER_DSN: "null://null"
|
|
APP_CONTAINER_NAME: web
|
|
ports:
|
|
- target: 80
|
|
published: *http_port
|
|
protocol: tcp
|
|
volumes:
|
|
# Named volumes rather than host paths: these hold TLS material
|
|
# Caddy regenerates by itself, so there is nothing here worth a
|
|
# dataset of its own — and two fewer paths to get right.
|
|
- type: volume
|
|
source: caddy_data
|
|
target: /data
|
|
- type: volume
|
|
source: caddy_config
|
|
target: /config
|
|
# One mount for everything plMail writes. APP_STORAGE_DIR and
|
|
# APP_SECRETS_* point inside it, so attachments, raw messages,
|
|
# uploads and the generated secrets all land here — and every
|
|
# service sees the same files, which the encryption key depends on.
|
|
- type: bind
|
|
source: *path_data
|
|
target: /app/var/data
|
|
bind:
|
|
create_host_path: true
|
|
depends_on:
|
|
secrets-init:
|
|
condition: service_completed_successfully
|
|
database:
|
|
condition: service_healthy
|
|
|
|
# Everything that is not the web server, in one container: the IMAP
|
|
# supervisor, one consumer per queue, the scheduler and the Mercure hub —
|
|
# seven processes, kept running by `app:work`. They used to be seven
|
|
# containers. Still one PROCESS per queue, so a send never waits behind a
|
|
# sync; only the containers merged.
|
|
#
|
|
# Answers to `mercure` on the network because it runs the hub, so the web
|
|
# container's proxy and MERCURE_URL reach it where they always reached the
|
|
# hub container.
|
|
worker:
|
|
image: *image
|
|
pull_policy: always
|
|
restart: unless-stopped
|
|
command: php bin/console app:work
|
|
# Reaps the IMAP supervisor's children should it die hard.
|
|
init: true
|
|
# Longer than app:work's own 25s, which it gives every process to
|
|
# finish the message in hand.
|
|
stop_grace_period: 30s
|
|
environment:
|
|
<<: *app-env
|
|
APP_CONTAINER_NAME: worker
|
|
networks:
|
|
default:
|
|
aliases: [mercure]
|
|
volumes:
|
|
# One mount for everything plMail writes, as on php.
|
|
- type: bind
|
|
source: *path_data
|
|
target: /app/var/data
|
|
bind:
|
|
create_host_path: true
|
|
# The hub's state, in the volumes the hub container used.
|
|
- type: volume
|
|
source: mercure_data
|
|
target: /data
|
|
- type: volume
|
|
source: mercure_config
|
|
target: /config
|
|
healthcheck:
|
|
disable: true
|
|
depends_on:
|
|
secrets-init:
|
|
condition: service_completed_successfully
|
|
database:
|
|
condition: service_healthy
|
|
|
|
database:
|
|
image: postgres:18-alpine
|
|
restart: unless-stopped
|
|
environment:
|
|
POSTGRES_DB: app
|
|
POSTGRES_USER: app
|
|
# Only the _FILE form: the image rejects both being set at once, and
|
|
# the file is written with whatever db_password holds — generated or
|
|
# yours — so it is always the effective password.
|
|
POSTGRES_PASSWORD_FILE: /plmail/secrets/postgres_password
|
|
PGDATA: /plmail/postgres
|
|
healthcheck:
|
|
test: ["CMD", "pg_isready", "-d", "app", "-U", "app"]
|
|
timeout: 5s
|
|
retries: 5
|
|
start_period: 60s
|
|
depends_on:
|
|
secrets-init:
|
|
condition: service_completed_successfully
|
|
volumes:
|
|
# PGDATA is a subfolder of the shared mount, so Postgres creates
|
|
# and owns it on first start — nothing to chown by hand.
|
|
- type: bind
|
|
source: *path_data
|
|
target: /plmail
|
|
bind:
|
|
create_host_path: true
|
|
command:
|
|
- "postgres"
|
|
- "-c"
|
|
- "shared_preload_libraries=pg_stat_statements"
|
|
- "-c"
|
|
- "pg_stat_statements.track=top"
|
|
|
|
volumes:
|
|
caddy_data:
|
|
caddy_config:
|
|
mercure_data:
|
|
mercure_config:
|