From 084b1bc2049ac035912d1ddf594851eda6e0d3c7 Mon Sep 17 00:00:00 2001 From: Lucas Rayan Date: Sun, 2 Aug 2026 19:15:43 -0300 Subject: [PATCH] #23: document the new sign-in path, container health and the gaps found The deployment guide still described enrolling a second factor from webmail settings before the console would open. That detour is gone: the console enrols one inline, and the console itself is now reached from a link inside the app rather than from a chooser at the root. Also records what the console does not do, since it previously implied otherwise on screen: DNS records are not verified per record, attachments are not uploaded, and the vacation responder, signature and Sieve rules are stored but not yet consumed during delivery. Co-Authored-By: Claude Opus 5 --- docs/DEPLOYMENT.md | 17 ++++++++++++----- docs/OPERATIONS.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 5 deletions(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index b2f0cd8..2f82fe5 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -134,12 +134,19 @@ This creates the domain if needed, the mailbox as `SUPER_ADMIN`, its standard folders, and the four system aliases (`postmaster@`, `abuse@`, `dmarc@`, `tlsrpt@`) that the published DNS records point at. -Then: +Then sign in at `https:///`, which opens the mail client. -1. Sign in to the webmail at `https:///user/login`. -2. Go to **Settings** and enrol a second factor. The admin console requires - one and will refuse to open until it exists. -3. Sign in to `https:///admin/login`. +An account that may administer the server gets an **Admin console** link in the +webmail sidebar. Following it asks for the password and second factor again, +because the console is a separate audience — being signed in to webmail is +never enough on its own. + +If the account has no second factor yet, the admin sign-in enrols one on the +spot: it shows a QR code to scan, takes the first code back, and hands over the +recovery codes. There is no need to visit another screen first, and no way to +end up locked out of the console for want of a factor you could not reach. + +Leaving the console needs nothing — the webmail session was never given up. ## Step 5 — DNS records diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 5b144ca..2970cf2 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -17,6 +17,25 @@ matters: Degraded is deliberately not a failure: restarting cannot fix a certificate the proxy never issued, and a restart loop would only hide it. +### Container health + +Every long-running service carries a Docker healthcheck, so `docker compose ps` +is a real answer rather than a list of processes that have not exited: + +```bash +docker compose ps --format 'table {{.Service}}\t{{.Status}}' +``` + +`migrate` is the one service without a probe, on purpose: it applies the +migrations and stops. Everything that needs it waits on +`service_completed_successfully`, which is a stronger guarantee than a probe — +a healthcheck there would report unhealthy exactly when the job had succeeded. + +The probes are shallow by design. `web` checks only that Next can route a +request; it does not reach through to `auth` or `protocols`, because a blip in +one backend should not mark the frontend unhealthy and take the site down with +it. Those services have probes of their own. + ## Certificates Under `TLS_MODE=traefik` the mail listeners read the certificate Coolify's proxy @@ -175,3 +194,14 @@ Being explicit so nothing is assumed: - Master key rotation is manual. - Log retention is whatever Docker's json-file driver is configured for (10 MB × 3 per service, in `docker-compose.yaml`). +- **Per-record DNS verification is not implemented.** The admin console's + reconcile button records the request and re-reads the stored status; it does + not query a resolver and compare the thirteen expected records. The console + used to draw a table of green ticks for records nobody had checked. Verify by + hand, or with `make preflight`, until this is real. +- **Attachments are not uploaded.** The compose screen lists the files you pick + and sends their names only; there is no upload endpoint behind the picker + yet. The screen says so when you attach something, rather than letting the + message leave without them. +- The vacation responder, the signature and the Sieve rules are stored, but + nothing consumes them during delivery yet.