Configuration
Direct execution uses the variables below. Start with .env.example. Docker production settings are supplied through oci.env.example and mapped by compose.oci.yml.
Application settings
| Variable | Default when omitted | Meaning |
|---|---|---|
NODE_ENV | Production mode is off | Exactly production enables HTTPS validation and secure cookies |
HOST | 127.0.0.1 | Listening interface; Compose uses 0.0.0.0 inside the container |
PORT | 4100 | Integer from 1 through 65535 |
AUTH_ORIGIN | http://localhost:4100 | Browser origin and OIDC issuer |
AUTH_API_ORIGIN | AUTH_ORIGIN | Advertised server-side OAuth endpoint origin |
AUTH_BACKEND | native | Set keycloak to delegate credentials and sign-in |
KEYCLOAK_ISSUER | Required for Keycloak | Public realm URL, such as https://auth.example.com/realms/techinject |
KEYCLOAK_BACKCHANNEL_URL | KEYCLOAK_ISSUER | Private realm URL for token, key, introspection and same-domain form requests; required on a separate origin when the public issuer uses AUTH_ORIGIN. Production requires HTTPS |
KEYCLOAK_CLIENT_ID | Required for Keycloak | Confidential OIDC broker client |
KEYCLOAK_CLIENT_SECRET | Required for Keycloak | Backend-only secret, distinct from downstream app credentials |
DATABASE_URL | Required | PostgreSQL connection URL |
ENCRYPTION_KEY | Required | Canonical base64url encoding of 32 random bytes |
SIGNING_KEY_PATH | .local/signing.pem | Path to an Ed25519 private key in PEM format |
MAIL_MODE | spool | spool, sendmail, or resend |
MAIL_FROM | Awwwth <accounts@example.com> | Sender address; replace for actual delivery |
RESEND_API_KEY | Empty | Required when mail mode is resend |
SENDMAIL_PATH | /usr/sbin/sendmail | Executable used by sendmail mode |
TRUSTED_PROXY_IP | Empty | Exact peer IP allowed to provide a valid X-Real-IP |
Origins must be canonical origins without a path, query, or trailing slash; for example, https://auth.example.com. Both origins must use HTTPS in production. Production rejects spool mode. Resend mode rejects a missing API key or an example.com sender.
The setup script defaults to .local/keys, while the configuration fallback for the signing key is .local/signing.pem. Set SIGNING_KEY_PATH=.local/keys/signing.pem, as the example environment does. AWWWTH_SECRET_DIRECTORY changes the setup script's output directory only.
Keys and persistence
bun run setup creates encryption.key and signing.pem only when missing, using restricted file permissions. The encryption key protects TOTP secrets, queued email bodies, authorization request data, and Keycloak tokens and PKCE verifiers. The signing key signs ID and logout tokens; its public key is exposed through /oauth/jwks.
Compose stores both files in secret_data and reads the encryption key into the app environment at startup. Back up these keys together with the database. There is no automated key rotation or multi-key migration workflow in this repository; replacing the encryption key makes existing encrypted data unreadable.
Browser and API origins
AUTH_API_ORIGIN changes discovery metadata, not the application's accepted Host header. The service still validates incoming requests against AUTH_ORIGIN. If the API has a separate public hostname, its reverse proxy must forward the issuer hostname upstream. See the Nginx template.
Account APIs are same-origin cookie APIs. The public /awwwth.js module permits cross-origin loading; that does not enable cross-origin calls to account or token APIs.
| Mode | Behavior |
|---|---|
spool | Writes private .eml files under .local/mail; development only |
resend | Sends through Resend with a delivery ID as the idempotency key |
sendmail | Invokes SENDMAIL_PATH -t -i; requires an installed executable and working relay |
The provided OCI override requires DOCKER_RESEND_API_KEY even if DOCKER_MAIL_MODE is changed. A sendmail deployment needs an adapted image/configuration and Compose override; changing the mode alone does not install a relay.
Tracing
| Variable | Purpose |
|---|---|
OTEL_SERVICE_NAME | Service name; application fallback is awwwth-auth |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP/HTTP exporter base endpoint; leave empty to disable export |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Optional trace-specific endpoint recognized by direct execution |
OTEL_EXPORTER_OTLP_HEADERS | Exporter authentication headers |
OTEL_RESOURCE_ATTRIBUTES | Resource metadata such as deployment environment |
OTEL_TRACES_SAMPLER | Sampler selection; example uses parentbased_traceidratio |
OTEL_TRACES_SAMPLER_ARG | Sampling argument; example uses 1 |
OTEL_SDK_DISABLED | Exactly true disables telemetry |
The supplied Compose file passes the common variables listed in .env.example; add an override to pass the trace-specific endpoint or SDK-disable flag. Request traces normalize unknown URL segments to :id and omit /healthz. A separate SigNoz configuration is in observability/casting.yaml.