From 6aecbf8493850444c3b67dd73c55c76299fb6176 Mon Sep 17 00:00:00 2001 From: Kirill Mokevnin Date: Sun, 15 Nov 2026 22:45:29 -0500 Subject: [PATCH] docs(configuration): read the configuration from the process environment only The binary reads no .env file and no `_FILE` sibling any more, and the Helm chart takes its secrets through existingSecret alone. The configuration reference is the new envdoc list, and the retention and live-window variables are Go durations under new names. Co-Authored-By: Claude Opus 5.5 --- src/content/docs/docs/configuration.md | 321 ++++++++++++------- src/content/docs/docs/export-streams.md | 2 +- src/content/docs/docs/guide/tracking.md | 2 +- src/content/docs/docs/operations/doctor.md | 2 +- src/content/docs/docs/operations/scaling.md | 14 +- src/content/docs/docs/operations/security.md | 2 +- src/content/docs/docs/self-hosting.md | 7 +- 7 files changed, 220 insertions(+), 130 deletions(-) diff --git a/src/content/docs/docs/configuration.md b/src/content/docs/docs/configuration.md index 6a11a0d..2761c74 100644 --- a/src/content/docs/docs/configuration.md +++ b/src/content/docs/docs/configuration.md @@ -2,21 +2,16 @@ title: "Configuration reference" --- - + -Every environment variable Sphericon reads, with its default. You do not need most of them: a -working Instance needs only the four [required ones](#required) and a mail provider (set up in the -app, see the [Quickstart](/docs/guide/quickstart)). The rest switch on specific features. +You do not need most of these variables: a working Instance needs only the four [required ones](#required) +and a mail provider (set up in the app, see the [Quickstart](/docs/guide/quickstart)). The rest switch on +specific features. Not installed yet? Start with [Self-hosting](/docs/self-hosting). -A value that breaks a rule stops the start with a message naming the variable. - -The process environment wins over the `.env` files of a checkout, which are read in this order, a later -one overriding an earlier: `.env`, `.env.`, `.env.local`, `.env..local` -(the `test` and `e2e` profiles read only their own `.env.`). - ## Required | Variable | What it is | @@ -26,113 +21,209 @@ one overriding an earlier: `.env`, `.env.`, `.env.local`, `.env.< | `SPHERICON_ENCRYPTION_KEY` | Encrypts stored provider credentials. Generate it with `sphericon genkey`. | | `SPHERICON_APP_URL` | The public `https://` origin of the Instance. Tracking and unsubscribe links are built from it. | -## Variables +Every environment variable Sphericon reads, with its default. The process environment is the only +source: the binary reads no `.env` file. Set the variables where the process starts: a Kubernetes +`env`/`envFrom` (a Secret through `secretKeyRef` or `secretRef`), a compose `environment`/`env_file`, +a systemd `Environment`/`EnvironmentFile`. A value that does not parse as its type, and a missing +required variable, stop the start. + +Two variables are read apart from the list below: + +- `SPHERICON_ENV`: the environment the process runs as. `production` (also when unset), or + `development`, `test` and `e2e` for a checkout's dev stack, the Go tests and the end-to-end suite. + It changes no default; `development` and `test` relax production-only behaviour such as the + development License key, and the release image sets `production`. +- `OTEL_CONFIG_FILE`: the path of an OpenTelemetry declarative configuration file (YAML), which says + where traces, metrics and logs are exported. Unset, nothing is exported over OTLP. -| Variable | Default | Rules | Secret | Description | -| --- | --- | --- | --- | --- | -| `SPHERICON_DATABASE_URL` | — | required | yes | The PostgreSQL connection string, such as `postgres://user:pass@host:5432/db?sslmode=require`; `sslmode=verify-full` with `sslrootcert` also verifies the server's certificate. The job queue LISTENs for new jobs on a session of its own: behind PgBouncer, it must reach Postgres directly or a pool in session mode, never transaction mode. | -| `PORT` | `3000` | | | The port the public HTTP server listens on, on every interface. | -| `SPHERICON_APP_URL` | `http://localhost:3000` | | | The public origin of the Instance, `https://` in production: sessions, mailed links and tracking and unsubscribe links are built on it, an `https://` origin makes the session cookie Secure, and its host is the Passkey relying party id (ADR 0052), so changing the host invalidates every registered Passkey. An Instance served on an IP address cannot use Passkeys. | -| `SPHERICON_MCP_URL` | — | | | The public origin of a dedicated MCP host, such as `https://mcp.example.com`: the MCP resource is then served there while the OAuth issuer and consent screen stay on `SPHERICON_APP_URL`. Empty serves MCP on `SPHERICON_APP_URL`. | -| `SPHERICON_TRACKER_URL` | — | | | The public origin the tracker snippet loads `/t.js` from and posts `/collect` to, such as `https://t.example.com`, when the tracker has a host of its own routed to the same Instance. Empty uses `SPHERICON_APP_URL`. | -| `SPHERICON_BOOTSTRAP_TOKEN` | — | | yes | The token the external API's bootstrap operation takes in `X-Bootstrap-Token` to mint an API token of the oldest Workspace without a caller token. Empty refuses every bootstrap. | -| `SPHERICON_CORS_ORIGINS` | — | | | Comma- or space-separated origins allowed credentialed CORS on the cookie-authenticated surfaces (`/site`, `/staff`). Empty is same-origin only, which the bundled app needs; the bearer-token surfaces answer any origin without credentials either way. | -| `SPHERICON_JWT_SECRET` | — | | yes | Signs sessions and mailed links. Outside development and test the start is refused when it is empty, shorter than 32 characters or a documented placeholder; generate one with `openssl rand -hex 32`. | -| `SPHERICON_JWT_SECRET_SECONDARY` | — | | yes | The second secret of a JWT secret rotation: accepted when a session or a mailed link is verified, never used to sign. It must differ from `SPHERICON_JWT_SECRET` and, outside development and test, holds the same rules. Empty outside a rotation. | -| `SPHERICON_SESSION_TTL` | `24h` | must be positive | | The lifetime of a site session, a Go duration such as `12h`: both the token's expiry and the cookie's, with no refresh (ADR 0020). | -| `SPHERICON_ENCRYPTION_KEY` | — | | yes | The base64 Tink keyset that encrypts stored provider credentials; the server does not start without one. Generate it with `sphericon genkey`. | -| `SPHERICON_LICENSE_KEY` | — | | yes | The Enterprise Edition license key (ADR 0014), a JWT signed with Ed25519. Empty runs the open core. An expired key also runs the open core and logs a warning (ADR 0035); a malformed key or one whose signature does not verify stops the start. | -| `SPHERICON_SMTP_HOST` | — | | | The host of the SMTP relay the Instance's own mail goes through when `SPHERICON_SYSTEM_EMAIL_PROVIDER` is `smtp`. Empty leaves the Instance without outbound mail. | -| `SPHERICON_SMTP_PORT` | `1025` | | | The port of the SMTP relay. | -| `SPHERICON_SMTP_USER` | — | | | The user the SMTP relay is authenticated as; empty sends without authentication. | -| `SPHERICON_SMTP_PASS` | — | | yes | The password of `SPHERICON_SMTP_USER`. | -| `SPHERICON_ACCOUNT_LINK_URL` | — | must be set together with `SPHERICON_ACCOUNT_LINK_SIGNING_KEY` | | The address of an external account page. With `SPHERICON_ACCOUNT_LINK_SIGNING_KEY`, a Workspace Owner sees an Account link that opens it with a signed token. The app never calls this address. | -| `SPHERICON_ACCOUNT_LINK_SIGNING_KEY` | — | must be set together with `SPHERICON_ACCOUNT_LINK_URL` | yes | The base64 Ed25519 seed that signs the Account link token (`openssl rand -base64 32`). The matching public key is published at `/.well-known/jwks.json`, so the receiver needs no secret. | -| `SPHERICON_STAFF_JWT_SECRET` | — | | yes | Signs the Staff member session and login challenge (ADR 0026, ADR 0063). Empty turns the Staff sign-in off; set, it must differ from `SPHERICON_JWT_SECRET`. The `staff` license feature and `SPHERICON_MODE=saas` require it. Generate one with `openssl rand -hex 32`. | -| `SPHERICON_STAFF_SESSION_TTL` | `4h` | must be positive | | The lifetime of a Staff member session, a Go duration: no refresh and no "remember me". | -| `SPHERICON_STAFF_HOLD_MAX_EXPIRY` | `720h` | must be positive | | How far ahead a service may set a Staff hold's expiry, a Go duration; a later expiry is refused. | -| `SPHERICON_ABUSE_VOLUME_FLOOR` | `1000` | must be positive | | The fewest sends in the trailing 24 hours, per Sending domain, for the abuse detector (`staff` license, ADR 0026) to judge its rates; below it nothing is warned or frozen. | -| `SPHERICON_ABUSE_WARN_COMPLAINT_PERCENT` | `0.1` | must be positive; must be below `SPHERICON_ABUSE_FREEZE_COMPLAINT_PERCENT` | | The complaint rate, in percent, at which the abuse detector warns the Workspace's Owners by email, freezing nothing. | -| `SPHERICON_ABUSE_WARN_BOUNCE_PERCENT` | `5` | must be positive; must be below `SPHERICON_ABUSE_FREEZE_BOUNCE_PERCENT` | | The bounce rate, in percent, at which the abuse detector warns the Workspace's Owners. | -| `SPHERICON_ABUSE_FREEZE_COMPLAINT_PERCENT` | `0.3` | must be at most 100 | | The complaint rate, in percent, at which the abuse detector suspends the whole Workspace and tells its Owners. | -| `SPHERICON_ABUSE_FREEZE_BOUNCE_PERCENT` | `10` | must be at most 100 | | The bounce rate, in percent, at which the abuse detector suspends the whole Workspace. | -| `SPHERICON_SUPPORT_EMAIL` | — | | | The support address shown to a Workspace's Owners with a suspension (banner and notice email), where they appeal. Empty shows none. | -| `SPHERICON_DB_AUTO_MIGRATE` | `false` | | | Applies the embedded migrations at start, convenient for a single replica. | -| `SPHERICON_DB_MIGRATE_TIMEOUT` | `10m` | | | With `SPHERICON_DB_AUTO_MIGRATE` on, the longest a start waits for the migration lock and the run before it fails, a Go duration; `0` is no limit. `sphericon migrate` has no limit. | -| `SPHERICON_MAX_BODY_BYTES` | `1048576` | must be positive | | The largest request body, in bytes, accepted on every surface but `/collect`; a larger one is answered `413`. | -| `SPHERICON_COLLECT_MAX_BODY_BYTES` | `512000` | must be positive | | The largest `/collect` batch (`POST /collect/events`), in bytes; a larger one is answered `413`. | -| `SPHERICON_COLLECT_MAX_EVENT_BYTES` | `32768` | must be positive | | The largest single `/collect` event, in bytes: an identify body, or each event of a batch; a larger one is answered `413`. | -| `SPHERICON_RATE_LIMIT_HUMAN_PER_MINUTE` | `60` | must not be negative | | Requests per minute per client IP and endpoint on the public human-facing endpoints (signup, invitation accept, consent confirm); over it `429` with `Retry-After`. | -| `SPHERICON_RATE_LIMIT_API_BURST_PER_SECOND` | `20` | must not be negative | | Requests per second per Workspace on `/api` and `/mcp` (one shared budget); over it `429` with `Retry-After`. | -| `SPHERICON_RATE_LIMIT_API_PER_MINUTE` | `600` | must not be negative | | Requests per minute per Workspace on `/api` and `/mcp`, stacked on the burst limit. | -| `SPHERICON_RATE_LIMIT_FAILED_AUTH_PER_MINUTE` | `30` | must not be negative | | Failed credential checks (bearer token, collect key) per minute per client IP; successful ones are not counted. | -| `SPHERICON_RATE_LIMIT_TRACKING_PER_MINUTE` | `600` | must not be negative | | Opens and clicks recorded per minute per client IP. It never refuses a recipient: over it the redirect or pixel is still served and the event is not recorded. | -| `SPHERICON_RATE_LIMIT_LOGIN_FAILURES` | `5` | must not be negative | | Failed logins one account may have within 15 minutes before login answers `429` with an exponentially growing delay, even for a correct password (no lockout). | -| `SPHERICON_RATE_LIMIT_LOGIN_IP_PER_MINUTE` | `20` | must not be negative | | Login requests per minute per client IP. | -| `SPHERICON_RATE_LIMIT_COLLECT_PER_MINUTE` | `6000` | must not be negative | | Requests per minute per Workspace on `/collect`, a budget of its own apart from `/api` and `/mcp`. | -| `SPHERICON_RATE_LIMIT_COLLECT_IP_PER_MINUTE` | `300` | must not be negative | | Requests per minute per client IP on `/collect`. | -| `SPHERICON_RATE_LIMIT_SERVICE_PER_MINUTE` | `600` | must not be negative | | Requests per minute per Service credential on the internal listener's service endpoints. | -| `SPHERICON_RATE_LIMIT_FORGOT_PASSWORD_PER_ADDRESS_PER_HOUR` | `3` | must not be negative | | Mails one address may be sent per hour by each of forgot-password, registration and an email-change request (ADR 0031). Over it the request is still answered `202` and nothing is sent, so the answer never tells whether the address has an account. | -| `SPHERICON_RATE_LIMIT_FORGOT_PASSWORD_IP_PER_HOUR` | `10` | must not be negative | | Forgot-password requests per client IP per hour; over it `429`. | -| `SPHERICON_EVENTS_RETENTION_DAYS` | `400` | must not be negative | | The age, in days, past which analytical Events are deleted by a daily job; `0` disables it (ADR 0019). Evidentiary Events (`marketing.confirmed`, `sms.confirmed`, `email.complained`, `email.unsubscribed`, a permanent `email.bounced`) are never deleted by age. | -| `SPHERICON_UNVERIFIED_USER_RETENTION_DAYS` | `7` | must not be negative | | The age, in days, past which an Unverified User with no Membership is deleted by a daily job, freeing the address; `0` disables it (ADR 0030). | -| `SPHERICON_EVENT_LIVE_WINDOW_HOURS` | `72` | must be at least 1 | | The age, in hours, past which the external API refuses a live Event as history that belongs in a Backfill. A Backfill and `/collect` are not limited. | -| `SPHERICON_TEST_INBOX_RETENTION_DAYS` | `7` | must be at least 1 | | How many days a Test inbox keeps a Captured message (ADR 0058). | -| `SPHERICON_TEST_INBOX_MAX_MESSAGES` | `200` | must be at least 1 | | How many Captured messages a Workspace's Test inbox keeps, the newest ones (ADR 0058). | -| `SPHERICON_DB_MAX_OPEN_CONNS` | `15` | must be positive | | The most open connections of one replica's `database/sql` pool (ent, the event bus, job workers). The defaults fit two replicas under Postgres' `max_connections=100`. | -| `SPHERICON_DB_MAX_IDLE_CONNS` | — | must not be negative; must not be above `SPHERICON_DB_MAX_OPEN_CONNS` | | The most idle connections that pool keeps. Empty is `SPHERICON_DB_MAX_OPEN_CONNS`. | -| `SPHERICON_DB_CONN_MAX_LIFETIME` | `30m` | must be positive | | The longest a pooled connection lives, a Go duration. | -| `SPHERICON_RIVER_DB_MAX_CONNS` | `25` | must be positive | | The most connections of the job queue's own pool (fetch, completion, leader election), plus one LISTEN connection outside it. Job workers use the `database/sql` pool, so it need not match their number. | -| `SPHERICON_SMTP_ALLOW_PRIVATE_HOSTS` | `false`; `true` in development and test | | | Lets a Workspace's SMTP Integration reach a loopback or private host on any port. Off, it may only reach a public host on port 25, 465, 587 or 2525. The Instance's own `SPHERICON_SMTP_HOST` is exempt. | -| `SPHERICON_OUTBOUND_ALLOW` | — | | | Comma-separated `host:port` pairs (a name or an IP address, one port each, no wildcards) that an outbound call to a third-party URL, such as a Webhook endpoint delivery, may reach although the address is private or loopback, such as `n8n:5678` (ADR 0039). Redirects are still never followed; a malformed value stops the start. Leave it empty on a multi-tenant host. | -| `SPHERICON_APP_LOCALE` | `en` | | | The Instance's language for the UI and its own mail. `en` is the only one; any other value becomes `en`. | -| `DO_NOT_TRACK` | — | | | `1` switches the Telemetry report off and locks the Owner's setting; it never switches the report on (ADR 0032). | -| `SPHERICON_MODE` | `selfhosted` | | | The kind of deployment, `selfhosted` or `saas` (ADR 0060): it alone decides the Release check, the Telemetry report, the email verification gate and the Sign-up survey. `saas` also requires `SPHERICON_STAFF_JWT_SECRET`, `SPHERICON_INTERNAL_ADDR`, `SPHERICON_TRACKING_CNAME_TARGET` and a system email provider. Any other value stops the start. | -| `SPHERICON_SENTRY_DSN` | — | | | The Sentry-compatible DSN the browser app reports its errors to, handed to the page when it is served. Empty leaves the browser reporting off. | -| `SPHERICON_SIGNIN_GOOGLE_CLIENT_ID` | — | | | The OAuth client id of the Instance's Google Cloud app: with its secret, enables "Continue with Google" (ADR 0048). Register `/site/auth/signin/google/callback` as its redirect URI. One of the pair without the other stops the start. | -| `SPHERICON_SIGNIN_GOOGLE_CLIENT_SECRET` | — | | yes | The OAuth client secret that goes with `SPHERICON_SIGNIN_GOOGLE_CLIENT_ID`. | -| `SPHERICON_SIGNIN_GITHUB_CLIENT_ID` | — | | | The OAuth client id of the Instance's GitHub OAuth app: with its secret, enables "Continue with GitHub" (ADR 0048). Set `/site/auth/signin/github/callback` as its callback URL. One of the pair without the other stops the start. | -| `SPHERICON_SIGNIN_GITHUB_CLIENT_SECRET` | — | | yes | The OAuth client secret that goes with `SPHERICON_SIGNIN_GITHUB_CLIENT_ID`. | -| `SPHERICON_LOG_LEVEL` | `info` | | | The log level: `debug`, `info`, `warn` or `error`, in any case; a value that names no level stops the start. | -| `SPHERICON_LOG_FORMAT` | `json`; `text` in development and test | | | The log format: `json`, or `text` for coloured human-readable lines; any other value stops the start. | -| `OTEL_SERVICE_NAME` | `sphericon` | | | The `service.name` reported on OpenTelemetry traces and metrics. | -| `SPHERICON_METRICS_ADDR` | — | | | The `host:port` of the opt-in Prometheus listener. Empty runs none; the public port never serves `/metrics` (ADR 0025). It must differ from `PORT`. | -| `SPHERICON_DNS_ADDR` | — | | | The `host:port` of a DNS server that verifies Sending domains and Join domains instead of the host's resolver, for a development stack that publishes its own records. Leave it empty in production. | -| `SPHERICON_INTERNAL_ADDR` | — | | | The `host:port` of the opt-in internal listener: the edge's on-demand TLS `ask` and, with the `staff` license, the service endpoints of the Staff surface (ADR 0026, ADR 0038). Empty runs none. It must differ from `PORT` and `SPHERICON_METRICS_ADDR`. | -| `SPHERICON_PRESETS_DIR` | — | | | A directory of custom Presets (ADR 0037): every `*.yaml` and `*.yml` file at its root loads beside the built-in ones at start, and a file that does not load, or reuses a built-in name, stops the start. Empty loads only the built-in Presets. | -| `SPHERICON_TELEGRAM_BOT_API_URL` | `https://api.telegram.org` | | | The base URL of the Telegram Bot API every Workspace's Telegram bot is reached at: Telegram's own server by default, or a local `telegram-bot-api` server (https://github.com/tdlib/telegram-bot-api) that runs the Bot API on your own infrastructure, such as `http://telegram-bot-api:8081`. Calls go to `/bot/`. | -| `SPHERICON_TWILIO_API_URL` | `https://api.twilio.com` | | | The base URL of Twilio's REST API every Workspace's SMS Integration is reached at: Twilio's own API by default, or a regional edge such as `https://api.dublin.ie1.twilio.com`. The Messaging Services API is reached at the same host with its first label `messaging` instead of `api`; a base whose host does not start with `api.` (a proxy, a test's fake) takes both APIs' calls. | -| `SPHERICON_TRACKING_CNAME_TARGET` | — | | | The edge host a Workspace's Tracking domain (e.g. `t.example.com`) is a CNAME to, such as `edge.example.com` (ADR 0038, ADR 0071). Empty turns Tracking domains off: the section is hidden on Settings, Tracking and no host is set or checked. | -| `SPHERICON_TRACKING_HOST_HEADER` | — | | | The request header the edge sets to the customer's host, such as `X-Forwarded-Host` (ADR 0038), believed only from a peer inside `SPHERICON_TRACKING_EDGE_CIDRS`. Empty uses the connection's `Host`. Have the proxy of the Instance's own host drop this header. | -| `SPHERICON_TRACKING_EDGE_CIDRS` | `127.0.0.0/8,::1/128` | | | Comma- or space-separated CIDRs the edge connects from: the only peers whose `SPHERICON_TRACKING_HOST_HEADER` is believed. A proxy on another machine must be listed. | -| `SPHERICON_SYSTEM_EMAIL_PROVIDER` | `smtp` | | | The provider of the Instance's own mail (verification, password reset, invitations): `smtp`, through `SPHERICON_SMTP_HOST`, or `ses`, through the `SPHERICON_SES_*` credentials. | -| `SPHERICON_SYSTEM_EMAIL_FROM` | `noreply@sphericon.localhost` | | | The From of the Instance's own mail: a bare address or `Name `. An invalid value stops the start. | -| `SPHERICON_SYSTEM_EMAIL_REPLY_TO` | — | | | One bare address, such as `replies@example.com`, put in the `Reply-To` of the Instance's own mail. Empty sets no header; an invalid value stops the start. | -| `SPHERICON_SES_REGION` | — | | | The region of the SES-compatible service of the `ses` provider. | -| `SPHERICON_SES_ACCESS_KEY_ID` | — | | yes | The access key id of the SES-compatible service of the `ses` provider. | -| `SPHERICON_SES_SECRET_ACCESS_KEY` | — | | yes | The secret access key of the SES-compatible service of the `ses` provider. | +The section between the markers below is generated by envdoc from the `env` tags and doc comments of +`config.Environment`: change the code and run `mise run generate:configdoc`, never edit it by hand. -## Variables read outside the configuration + -| Variable | Default | Rules | Secret | Description | -| --- | --- | --- | --- | --- | -| `SPHERICON_ENV` | — | | | The profile the process runs under, read before anything else: it picks the `.env` files and the defaults that depend on it. `development` (also when empty), `test` and `e2e` tolerate a missing `SPHERICON_JWT_SECRET` and let a Workspace's SMTP Integration reach a private host; `development` and `test` log as text, and `e2e`, the end-to-end suite's profile, has no rate limits. Any other name is a production profile. The release image sets `production`. | -| `OTEL_CONFIG_FILE` | — | | | Path of an OpenTelemetry declarative configuration file (YAML), which says where traces, metrics and logs are exported. Unset, nothing is exported over OTLP. | +## Environment -## Secrets from files +Environment is every variable the Instance reads, with its default. -Docker and Kubernetes mount secrets as files. Each secret variable also accepts a `_FILE` sibling (`SPHERICON_JWT_SECRET_FILE=/run/secrets/jwt`) whose value is the path of a file read at start; the trailing newline is trimmed. A value set directly wins and its file is never read; an unreadable or empty file stops the start, naming the `_FILE` variable. `sphericon doctor` redacts every secret value from what it prints. The secret variables: + - `PORT` (default: `3000`) - The port the public HTTP server listens on, on every interface. + - `SPHERICON_ENCRYPTION_KEY` (**required**, non-empty) - The base64 Tink keyset that encrypts stored provider credentials; the start is refused without +it. Generate it with `sphericon genkey`. + - `SPHERICON_DATABASE_URL` (**required**, non-empty) - The PostgreSQL connection string, such as `postgres://user:pass@host:5432/db?sslmode=require`; +`sslmode=verify-full` with `sslrootcert` also verifies the server's certificate. The job queue +LISTENs for new jobs on a session of its own: behind PgBouncer, it must reach Postgres directly +or a pool in session mode, never transaction mode. + - `SPHERICON_APP_URL` (default: `http://localhost:3000`) - The public origin of the Instance, `https://` in production: sessions, mailed links and +tracking and unsubscribe links are built on it, an `https://` origin makes the session cookie +Secure, and its host is the Passkey relying party id (ADR 0052), so changing the host +invalidates every registered Passkey. An Instance served on an IP address cannot use Passkeys. + - `SPHERICON_MCP_URL` - The public origin of a dedicated MCP host, such as `https://mcp.example.com`: the MCP resource +is then served there while the OAuth issuer and consent screen stay on `SPHERICON_APP_URL`. +Empty serves MCP on `SPHERICON_APP_URL`. + - `SPHERICON_TRACKER_URL` - The public origin the tracker snippet loads `/t.js` from and posts `/collect` to, such as +`https://t.example.com`, when the tracker has a host of its own routed to the same Instance. +Empty uses `SPHERICON_APP_URL`. + - `SPHERICON_BOOTSTRAP_TOKEN` - The token the external API's bootstrap operation takes in `X-Bootstrap-Token` to mint an API +token of the oldest Workspace without a caller token. Empty refuses every bootstrap. + - `SPHERICON_CORS_ORIGINS` - Comma-separated origins allowed credentialed CORS on the cookie-authenticated surfaces +(`/site`, `/staff`). Empty is same-origin only, which the bundled app needs; the bearer-token +surfaces answer any origin without credentials either way. + - `SPHERICON_JWT_SECRET` (**required**, non-empty) - Signs sessions and mailed links; the start is refused without it. Generate one with +`openssl rand -hex 32`. + - `SPHERICON_JWT_SECRET_SECONDARY` - The second secret of a JWT secret rotation: accepted when a session or a mailed link is +verified, never used to sign. Empty outside a rotation. + - `SPHERICON_SESSION_TTL` (default: `24h`) - The lifetime of a site session, a Go duration such as `12h`: both the token's expiry and the +cookie's, with no refresh (ADR 0020). + - `SPHERICON_LICENSE_KEY` - The Enterprise Edition license key (ADR 0014), a JWT signed with Ed25519. Empty runs the open +core. An expired key also runs the open core and logs a warning (ADR 0035); a malformed key or +one whose signature does not verify stops the start. + - `SPHERICON_SMTP_HOST` - The host of the SMTP relay the Instance's own mail goes through when +`SPHERICON_SYSTEM_EMAIL_PROVIDER` is `smtp`. Empty leaves the Instance without outbound mail. + - `SPHERICON_SMTP_PORT` (default: `1025`) - The port of the SMTP relay. + - `SPHERICON_SMTP_USER` - The user the SMTP relay is authenticated as; empty sends without authentication. + - `SPHERICON_SMTP_PASS` - The password of `SPHERICON_SMTP_USER`. + - `SPHERICON_ACCOUNT_LINK_URL` - The address of an external account page. With `SPHERICON_ACCOUNT_LINK_SIGNING_KEY`, a +Workspace Owner sees an Account link that opens it with a signed token. The app never calls +this address. + - `SPHERICON_ACCOUNT_LINK_SIGNING_KEY` - The base64 Ed25519 seed that signs the Account link token (`openssl rand -base64 32`). The +matching public key is published at `/.well-known/jwks.json`, so the receiver needs no secret. + - `SPHERICON_STAFF_JWT_SECRET` - Signs the Staff member session and login challenge (ADR 0026, ADR 0063). Empty turns the Staff +sign-in off; set, it must differ from `SPHERICON_JWT_SECRET`. The `staff` license feature +requires it. Generate one with `openssl rand -hex 32`. + - `SPHERICON_STAFF_SESSION_TTL` (default: `4h`) - The lifetime of a Staff member session, a Go duration: no refresh and no "remember me". + - `SPHERICON_STAFF_HOLD_MAX_EXPIRY` (default: `720h`) - How far ahead a service may set a Staff hold's expiry, a Go duration; a later expiry is +refused. + - `SPHERICON_ABUSE_VOLUME_FLOOR` (default: `1000`) - The fewest sends in the trailing 24 hours, per Sending domain, for the abuse detector (`staff` +license, ADR 0026) to judge its rates; below it nothing is warned or frozen. + - `SPHERICON_ABUSE_WARN_COMPLAINT_PERCENT` (default: `0.1`) - The complaint rate, in percent, at which the abuse detector warns the Workspace's Owners by +email, freezing nothing. + - `SPHERICON_ABUSE_WARN_BOUNCE_PERCENT` (default: `5`) - The bounce rate, in percent, at which the abuse detector warns the Workspace's Owners. + - `SPHERICON_ABUSE_FREEZE_COMPLAINT_PERCENT` (default: `0.3`) - The complaint rate, in percent, at which the abuse detector suspends the whole Workspace and +tells its Owners. + - `SPHERICON_ABUSE_FREEZE_BOUNCE_PERCENT` (default: `10`) - The bounce rate, in percent, at which the abuse detector suspends the whole Workspace. + - `SPHERICON_SUPPORT_EMAIL` - The support address shown to a Workspace's Owners with a suspension (banner and notice email), +where they appeal. Empty shows none. + - `SPHERICON_DB_AUTO_MIGRATE` - Applies the embedded migrations at start, convenient for a single replica. + - `SPHERICON_DB_MIGRATE_TIMEOUT` (default: `10m`) - With `SPHERICON_DB_AUTO_MIGRATE` on, the longest a start waits for the migration lock and +the run before it fails, a Go duration; `0` is no limit. `sphericon migrate` has no limit. + - The request body limits. + - `SPHERICON_MAX_BODY_BYTES` (default: `1048576`) - The largest request body, in bytes, accepted on every surface but `/collect`; a larger one is +answered `413`. + - `SPHERICON_COLLECT_MAX_BODY_BYTES` (default: `512000`) - The largest `/collect` batch (`POST /collect/events`), in bytes; a larger one is answered `413`. + - `SPHERICON_COLLECT_MAX_EVENT_BYTES` (default: `32768`) - The largest single `/collect` event, in bytes: an identify body, or each event of a batch; a +larger one is answered `413`. + - The per-policy rate limits (ADR 0025); `0` disables a limit. + - `SPHERICON_RATE_LIMIT_HUMAN_PER_MINUTE` (default: `60`) - Requests per minute per client IP and endpoint on the public human-facing endpoints +(signup, invitation accept, consent confirm); over it `429` with `Retry-After`. + - `SPHERICON_RATE_LIMIT_API_BURST_PER_SECOND` (default: `20`) - Requests per second per Workspace on `/api` and `/mcp` (one shared budget); over it `429` +with `Retry-After`. + - `SPHERICON_RATE_LIMIT_API_PER_MINUTE` (default: `600`) - Requests per minute per Workspace on `/api` and `/mcp`, stacked on the burst limit. + - `SPHERICON_RATE_LIMIT_FAILED_AUTH_PER_MINUTE` (default: `30`) - Failed credential checks (bearer token, collect key) per minute per client IP; successful +ones are not counted. + - `SPHERICON_RATE_LIMIT_TRACKING_PER_MINUTE` (default: `600`) - Opens and clicks recorded per minute per client IP. It never refuses a recipient: over it the +redirect or pixel is still served and the event is not recorded. + - `SPHERICON_RATE_LIMIT_LOGIN_FAILURES` (default: `5`) - Failed logins one account may have within 15 minutes before login answers `429` with an +exponentially growing delay, even for a correct password (no lockout). + - `SPHERICON_RATE_LIMIT_LOGIN_IP_PER_MINUTE` (default: `20`) - Login requests per minute per client IP. + - `SPHERICON_RATE_LIMIT_COLLECT_PER_MINUTE` (default: `6000`) - Requests per minute per Workspace on `/collect`, a budget of its own apart from `/api` and +`/mcp`. + - `SPHERICON_RATE_LIMIT_COLLECT_IP_PER_MINUTE` (default: `300`) - Requests per minute per client IP on `/collect`. + - `SPHERICON_RATE_LIMIT_SERVICE_PER_MINUTE` (default: `600`) - Requests per minute per Service credential on the internal listener's service endpoints. + - `SPHERICON_RATE_LIMIT_FORGOT_PASSWORD_PER_ADDRESS_PER_HOUR` (default: `3`) - Mails one address may be sent per hour by each of forgot-password, registration and an +email-change request (ADR 0031). Over it the request is still answered `202` and nothing is +sent, so the answer never tells whether the address has an account. + - `SPHERICON_RATE_LIMIT_FORGOT_PASSWORD_IP_PER_HOUR` (default: `10`) - Forgot-password requests per client IP per hour; over it `429`. + - `SPHERICON_EVENTS_RETENTION` (default: `9600h`) - The age past which analytical Events are deleted by a daily job, a Go duration such as +`9600h` (400 days); `0` disables it (ADR 0019). Evidentiary Events (`marketing.confirmed`, +`sms.confirmed`, `email.complained`, `email.unsubscribed`, a permanent `email.bounced`) are +never deleted by age. Rule Firings and the receipts that reject a redelivered external fact +end with the same window. + - `SPHERICON_MESSAGES_RETENTION` (default: `9600h`) - The age past which a daily job deletes Outbound messages, Broadcast recipients and tracked +links, keeping the Broadcast and Automation figures they made (ADR 0143), a Go duration; `0` +disables it. A finished Broadcast goes whole once it has been finished that long. The +analytics overview reads 180 days (`4320h`) back, so keep at least that. + - `SPHERICON_UNVERIFIED_USER_RETENTION` (default: `168h`) - The age past which an Unverified User with no Membership is deleted by a daily job, freeing +the address, a Go duration; `0` disables it (ADR 0030). + - `SPHERICON_EVENT_LIVE_WINDOW` (default: `72h`) - The age past which the external API refuses a live Event as history that belongs in a +Backfill, a Go duration. A Backfill and `/collect` are not limited. + - `SPHERICON_TEST_INBOX_RETENTION` (default: `168h`) - How long a Test inbox keeps a Captured message, a Go duration (ADR 0058). + - `SPHERICON_TEST_INBOX_MAX_MESSAGES` (default: `200`) - How many Captured messages a Workspace's Test inbox keeps, the newest ones (ADR 0058). + - The Postgres connection pools of one replica. + - `SPHERICON_DB_MAX_OPEN_CONNS` (default: `15`) - The most open connections of one replica's `database/sql` pool (ent, the event bus, job +workers). The defaults fit two replicas under Postgres' `max_connections=100`. + - `SPHERICON_DB_MAX_IDLE_CONNS` (expand, default: `${SPHERICON_DB_MAX_OPEN_CONNS}`) - The most idle connections that pool keeps. Empty is `SPHERICON_DB_MAX_OPEN_CONNS`. +It is declared after MaxOpenConns: the expansion reads that field's parsed value. + - `SPHERICON_DB_CONN_MAX_LIFETIME` (default: `30m`) - The longest a pooled connection lives, a Go duration. + - `SPHERICON_RIVER_DB_MAX_CONNS` (default: `25`) - The most connections of the job queue's own pool (fetch, completion, leader election), plus +one LISTEN connection outside it. Job workers use the `database/sql` pool, so it need not +match their number. + - `SPHERICON_SMTP_ALLOW_PRIVATE_HOSTS` - Lets a Workspace's SMTP Integration reach a loopback or private host on any port. Off, it may +only reach a public host on port 25, 465, 587 or 2525. The Instance's own +`SPHERICON_SMTP_HOST` is exempt. + - `SPHERICON_OUTBOUND_ALLOW` - Comma-separated `host:port` pairs (a name or an IP address, one port each, no wildcards) that +an outbound call to a third-party URL, such as a Webhook endpoint delivery, may reach although +the address is private or loopback, such as `n8n:5678` (ADR 0039). Redirects are still never +followed; a malformed value stops the start. Leave it empty on a multi-tenant host. + - `SPHERICON_APP_LOCALE` (default: `en`) - The Instance's language for the UI and its own mail. `en` is the only one. + - `DO_NOT_TRACK` - `true` (or `1`) switches the Telemetry report off and locks the Owner's setting; it never +switches the report on (ADR 0032). + - `SPHERICON_MODE` (default: `selfhosted`) - The kind of deployment, `selfhosted` or `saas` (ADR 0060): it alone decides the Release check, +the Telemetry report, the email verification gate and the Sign-up survey. Any other value +stops the start. + - `SPHERICON_SENTRY_DSN` - The Sentry-compatible DSN the browser app reports its errors to, handed to the page when it is +served. Empty leaves the browser reporting off. + - The Sign-in providers' OAuth clients (ADR 0048). + - Google enables "Continue with Google". Register +`/site/auth/signin/google/callback` as the redirect URI of the Instance's +Google Cloud app. + - `SPHERICON_SIGNIN_GOOGLE_CLIENT_ID` - The OAuth client id of the provider's app; set, it enables the provider. + - `SPHERICON_SIGNIN_GOOGLE_CLIENT_SECRET` - The OAuth client secret of the provider's app. + - GitHub enables "Continue with GitHub". Set `/site/auth/signin/github/callback` +as the callback URL of the Instance's GitHub OAuth app. + - `SPHERICON_SIGNIN_GITHUB_CLIENT_ID` - The OAuth client id of the provider's app; set, it enables the provider. + - `SPHERICON_SIGNIN_GITHUB_CLIENT_SECRET` - The OAuth client secret of the provider's app. + - `SPHERICON_LOG_LEVEL` (default: `info`) - The log level: `debug`, `info`, `warn` or `error`, in any case; a value that names no level +stops the start. + - `SPHERICON_LOG_FORMAT` (default: `json`) - The log format: `json`, or `text` for coloured human-readable lines; any other value stops the +start. + - `OTEL_SERVICE_NAME` (default: `sphericon`) - The `service.name` reported on OpenTelemetry traces and metrics. The export destinations come +from the declarative configuration file `OTEL_CONFIG_FILE` names. + - `SPHERICON_METRICS_ADDR` - The `host:port` of the opt-in Prometheus listener. Empty runs none; the public port never +serves `/metrics` (ADR 0025). Give it a port other than `PORT`. + - `SPHERICON_DNS_ADDR` - The `host:port` of a DNS server that verifies Sending domains and Join domains instead of the +host's resolver, for a development stack that publishes its own records. Leave it empty in +production. + - `SPHERICON_INTERNAL_ADDR` - The `host:port` of the opt-in internal listener: the edge's on-demand TLS `ask` and, with the +`staff` license, the service endpoints of the Staff surface (ADR 0026, ADR 0038). Empty runs +none. Give it a port other than `PORT` and `SPHERICON_METRICS_ADDR`'s. + - `SPHERICON_PRESETS_DIR` - A directory of custom Presets (ADR 0037): every `*.yaml` and `*.yml` file at its root loads +beside the built-in ones at start, and a file that does not load, or reuses a built-in name, +stops the start. Empty loads only the built-in Presets. + - `SPHERICON_TELEGRAM_BOT_API_URL` (default: `https://api.telegram.org`) - The base URL, without a trailing slash, of the Telegram Bot API every Workspace's Telegram bot +is reached at: Telegram's own server by default, or a local `telegram-bot-api` server +(https://github.com/tdlib/telegram-bot-api) that runs the Bot API on your own infrastructure, +such as `http://telegram-bot-api:8081`. Calls go to `/bot/`. + - `SPHERICON_TWILIO_API_URL` (default: `https://api.twilio.com`) - The base URL, without a trailing slash, of Twilio's REST API every Workspace's SMS Integration +is reached at: Twilio's own API by default, or a regional edge such as +`https://api.dublin.ie1.twilio.com`. The Messaging Services API is reached at the same host +with its first label `messaging` instead of `api`; a base whose host does not start with +`api.` (a proxy, a test's fake) takes both APIs' calls. + - `SPHERICON_TRACKING_CNAME_TARGET` - The edge host a Workspace's Tracking domain (e.g. `t.example.com`) is a CNAME to, such as +`edge.example.com`, in lowercase and without a trailing dot (ADR 0038, ADR 0071). Empty turns +Tracking domains off: the section is hidden on Settings, Tracking and no host is set or +checked. + - `SPHERICON_TRACKING_HOST_HEADER` - The request header the edge sets to the customer's host, such as `X-Forwarded-Host` (ADR +0038), believed only from a peer inside `SPHERICON_TRACKING_EDGE_CIDRS`. Empty uses the +connection's `Host`. Have the proxy of the Instance's own host drop this header. + - `SPHERICON_TRACKING_EDGE_CIDRS` (default: `127.0.0.0/8,::1/128`) - Comma-separated CIDRs the edge connects from: the only peers whose +`SPHERICON_TRACKING_HOST_HEADER` is believed. A proxy on another machine must be listed. + - `SPHERICON_SYSTEM_EMAIL_PROVIDER` (default: `smtp`) - The provider of the Instance's own mail (verification, password reset, invitations): `smtp`, +through `SPHERICON_SMTP_HOST`, or `ses`, through the `SPHERICON_SES_*` credentials. + - `SPHERICON_SYSTEM_EMAIL_FROM` (default: `noreply@sphericon.localhost`) - The bare From address of the Instance's own mail, such as `noreply@example.com`. + - `SPHERICON_SYSTEM_EMAIL_FROM_NAME` - The display name of the From of the Instance's own mail; empty sends the bare address. + - `SPHERICON_SYSTEM_EMAIL_REPLY_TO` - One bare address, such as `replies@example.com`, put in the `Reply-To` of the Instance's own +mail. Empty sets no header. + - `SPHERICON_SES_REGION` - The region of the SES-compatible service of the `ses` provider. + - `SPHERICON_SES_ACCESS_KEY_ID` - The access key id of the SES-compatible service of the `ses` provider. + - `SPHERICON_SES_SECRET_ACCESS_KEY` - The secret access key of the SES-compatible service of the `ses` provider. -- `SPHERICON_DATABASE_URL` -- `SPHERICON_JWT_SECRET` -- `SPHERICON_JWT_SECRET_SECONDARY` -- `SPHERICON_STAFF_JWT_SECRET` -- `SPHERICON_ENCRYPTION_KEY` -- `SPHERICON_SMTP_PASS` -- `SPHERICON_LICENSE_KEY` -- `SPHERICON_SES_ACCESS_KEY_ID` -- `SPHERICON_SES_SECRET_ACCESS_KEY` -- `SPHERICON_ACCOUNT_LINK_SIGNING_KEY` -- `SPHERICON_BOOTSTRAP_TOKEN` -- `SPHERICON_SIGNIN_GOOGLE_CLIENT_SECRET` -- `SPHERICON_SIGNIN_GITHUB_CLIENT_SECRET` + diff --git a/src/content/docs/docs/export-streams.md b/src/content/docs/docs/export-streams.md index b564089..993b072 100644 --- a/src/content/docs/docs/export-streams.md +++ b/src/content/docs/docs/export-streams.md @@ -100,7 +100,7 @@ own copy the same way to find the rows (`lower(hex(SHA256(lower(email))))` in Cl Events by Contact and Visitor. Use the hashes on Contacts and Outbound messages. Erasure rows are kept for the instance's Event retention window -(`SPHERICON_EVENTS_RETENTION_DAYS`, 400 days by default), and for good when retention is off. +(`SPHERICON_EVENTS_RETENTION`, 400 days by default), and for good when retention is off. Deletion by retention is not announced: your copy follows your own retention. Apply the erasures after loading the other streams, on every run: deleting twice is harmless. diff --git a/src/content/docs/docs/guide/tracking.md b/src/content/docs/docs/guide/tracking.md index 383d142..9da3221 100644 --- a/src/content/docs/docs/guide/tracking.md +++ b/src/content/docs/docs/guide/tracking.md @@ -176,7 +176,7 @@ curl https://sphericon.example.com/api/events/batch \ webhook endpoint receives it, so loading history never sends mail. - Every backfilled event needs an `occurredAt` that has already passed. - Without `backfill`, an event whose `occurredAt` is more than 72 hours old is refused with a - message that names `backfill` (the window is `SPHERICON_EVENT_LIVE_WINDOW_HOURS`). `/collect` is + message that names `backfill` (the window is `SPHERICON_EVENT_LIVE_WINDOW`). `/collect` is not limited. - An event with a `clientEventId` that is already stored changes nothing, so a load that broke off halfway is resent from the start. The id is unique within the Workspace. diff --git a/src/content/docs/docs/operations/doctor.md b/src/content/docs/docs/operations/doctor.md index 29fb69b..5f178c1 100644 --- a/src/content/docs/docs/operations/doctor.md +++ b/src/content/docs/docs/operations/doctor.md @@ -2,7 +2,7 @@ title: "Diagnosing an Instance with `sphericon doctor`" --- -`sphericon doctor` reads the same configuration as the server (the environment and `.env` files) +`sphericon doctor` reads the same configuration as the server (the process environment) and checks an Instance from the outside, so you can find what is wrong without asking for help. Each failed check prints the fix under it. It changes nothing and sends no mail. diff --git a/src/content/docs/docs/operations/scaling.md b/src/content/docs/docs/operations/scaling.md index c505ab6..46fe166 100644 --- a/src/content/docs/docs/operations/scaling.md +++ b/src/content/docs/docs/operations/scaling.md @@ -46,12 +46,12 @@ per client connection. There is no PgBouncer-compatible mode. The data that grows with traffic is the **Event** table. It is pruned in core by a background job. The policy is [ADR 0019](https://github.com/getsphericon/sphericon/blob/main/docs/adr/0019-event-retention.md). -| Variable | Default | `0` means | What it controls | -| --------------------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `SPHERICON_EVENTS_RETENTION_DAYS` | `400` | disabled | Deletes **analytical** Events (opens, clicks, deliveries, customer-tracked actions) older than the window, measured from when the row was inserted. Runs daily at 03:00 UTC, in small batches. | +| Variable | Default | `0` means | What it controls | +| ---------------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `SPHERICON_EVENTS_RETENTION` | `9600h` | disabled | Deletes **analytical** Events (opens, clicks, deliveries, customer-tracked actions) older than the window, measured from when the row was inserted. Runs daily at 03:00 UTC, in small batches. | -Negative values are rejected at startup. Deleting an Event is irreversible, so choose the window -deliberately; to keep everything, set `SPHERICON_EVENTS_RETENTION_DAYS=0`. +The window is a Go duration: `9600h` is 400 days. Deleting an Event is irreversible, so choose the +window deliberately; to keep everything, set `SPHERICON_EVENTS_RETENTION=0`. ### What is kept @@ -68,7 +68,7 @@ deliberately; to keep everything, set `SPHERICON_EVENTS_RETENTION_DAYS=0`. ### Segment look-back cap A [Segment](/docs/guide/segments) condition that looks back further than the retention window only -sees Events that still exist, so its results are capped by `SPHERICON_EVENTS_RETENTION_DAYS`. For example, +sees Events that still exist, so its results are capped by `SPHERICON_EVENTS_RETENTION`. For example, "opened an email in the last 500 days" behaves like "in the last 400 days" on a default instance. This is a documented product limit, not a bug. Evidentiary Events are exempt from the deletion, so conditions on them are not capped. @@ -84,5 +84,5 @@ queue, is the durable record of what happened. ## Disk Disk follows the Event rate. With the default window, expect the `events` table to level off at -roughly 400 days of analytical traffic plus all evidentiary Events. Lower `SPHERICON_EVENTS_RETENTION_DAYS` +roughly 400 days of analytical traffic plus all evidentiary Events. Lower `SPHERICON_EVENTS_RETENTION` to cap disk and backup size sooner. diff --git a/src/content/docs/docs/operations/security.md b/src/content/docs/docs/operations/security.md index 739080d..119140a 100644 --- a/src/content/docs/docs/operations/security.md +++ b/src/content/docs/docs/operations/security.md @@ -60,7 +60,7 @@ After any rotation, record the new value in your secret store before you discard `SPHERICON_ENCRYPTION_KEY` is a Tink keyset: it holds several keys, one of them primary. New secrets are encrypted under the primary key and every key in the keyset can still decrypt, so a rotation is a sequence you can stop after any step. The commands read the keyset from -`SPHERICON_ENCRYPTION_KEY` (or its `_FILE`); `rotate` and `retire` need no database and print the +`SPHERICON_ENCRYPTION_KEY`; `rotate` and `retire` need no database and print the new keyset on stdout, so capture it: 1. **Rotate.** `sphericon encryption-key rotate` adds a new primary key and prints the new keyset. diff --git a/src/content/docs/docs/self-hosting.md b/src/content/docs/docs/self-hosting.md index b0eec5a..5d06e9c 100644 --- a/src/content/docs/docs/self-hosting.md +++ b/src/content/docs/docs/self-hosting.md @@ -410,10 +410,9 @@ through the release that backfills the ids first if you skipped it. After the up The chart lives in `charts/sphericon` and is published at every release as an OCI artifact, `oci://ghcr.io/getsphericon/charts/sphericon`, with the chart version equal to the app version. Create a Secret with `SPHERICON_DATABASE_URL`, `SPHERICON_JWT_SECRET` and `SPHERICON_ENCRYPTION_KEY` first and -pass its name as `existingSecret` (the chart refuses to render without it). To hand the secrets over as -files instead (see [Secrets from files](/docs/configuration#secrets-from-files)), set `secretFiles.secretName` to the Secret -and `secretFiles.keys` to the variables it holds: the chart mounts it at `/run/secrets/sphericon` and sets -each `_FILE`; `existingSecret` is then optional. +pass its name as `existingSecret` (the chart refuses to render without it); the chart exports every key of +the Secret as an environment variable, so put any other secret variable, such as `SPHERICON_SMTP_PASS`, in +it too. ```sh helm install sphericon oci://ghcr.io/getsphericon/charts/sphericon \