Skip to main content

Environment variables

Everything goes in .env. Compose reads it for the ${...} values in docker-compose.yml, and env_file: .env hands it to the API. Values with spaces need quotes: MAIL_FROM="Linkdean <[email protected]>".

An unset variable takes its default. An empty one (SMTP_HOST=) counts as unset.

Published copy: docs.linkdean.app. Install steps: quick-start.md. Operations: operations.md.

Required​

The stack does not start without these. Generate each with openssl rand -hex 32: hex stays valid inside the database URL. The API refuses the example values published in this repository.

VariableWhat it does
POSTGRES_PASSWORDPassword of the linkdean database user. Postgres applies it only when the pgdata volume is first created; changing it later needs ALTER USER, see Upgrading an existing install
MEILI_MASTER_KEYMeilisearch master key. The search container runs with it, and the API uses it to index and search. At least 16 bytes
SESSION_SECRETAt least 16 characters. Signs the one-click unsubscribe links in notification email, so changing it voids links already sent. Sessions are random tokens stored hashed in Postgres, not signed with this
VariableDefaultWhat it does
LINKDEAN_VERSIONlatestImage tag to run. Pin a release such as 0.0.1 so upgrades happen only when you change it
APP_URLhttp://localhost:8080Public address of the instance, with no trailing slash. Used for links in emails, the SSO callback and the allowed browser origin. An https:// value also marks the session cookie Secure. Set it whenever the instance is reached by any other address
TRUST_FORWARDED_FORfalseSet true when a reverse proxy (Caddy, nginx, Traefik, a tunnel) is the only route to the API. Login and registration limits then count each client by the last X-Forwarded-For entry. Unset behind a proxy, every user shares the proxy's address and one person's failed logins can lock everyone out. Leave it unset when the API is reachable directly, because clients could forge the header
HSTS_MAX_AGEunsetWhen set to a number of seconds, every response includes Strict-Transport-Security: max-age=<n>; includeSubDomains. Leave unset on plain HTTP (including local Docker) so browsers are not stuck requiring HTTPS. On linkdean.app behind Cloudflare Tunnel you can also set HSTS at the edge instead
BOOTSTRAP_TOKENunsetWhen set, the first account (the admin) must enter it on the setup page and must use a password, not SSO. Unset, whoever registers first owns the instance. Ignored once any account exists

true, 1, yes and on all switch a true/false setting on. Anything else is off.

Email​

Off unless both SMTP_HOST and MAIL_FROM are set. Without it the instance sends nothing. Provider examples and the admin test page: Email.

VariableDefaultWhat it does
SMTP_HOSTunsetSMTP server host name
MAIL_FROMunsetSender mailbox, such as "Linkdean <[email protected]>"
SMTP_TLSstarttlsstarttls, tls (implicit TLS) or none. none sends mail unencrypted and is refused unless the host is localhost, a loopback or private address, or a single-label name such as mailpit. Use it only on a network you control
SMTP_PORT587, or 465 with SMTP_TLS=tlsSMTP port
SMTP_USERNAMEunsetSMTP login. Set together with SMTP_PASSWORD, or leave both unset
SMTP_PASSWORDunsetSMTP password, used exactly as given

The API refuses to start when only one of a pair is set, SMTP_TLS or SMTP_PORT is invalid, or MAIL_FROM is not a valid mailbox.

Sign-up protection​

Off by default. Public beta hosts usually set all three with SMTP.

VariableDefaultWhat it does
TURNSTILE_SITE_KEYunsetCloudflare Turnstile site key. With TURNSTILE_SECRET_KEY, password registration shows a captcha and the API checks the token with Siteverify. OIDC sign-in is unchanged
TURNSTILE_SECRET_KEYunsetTurnstile secret. Set together with TURNSTILE_SITE_KEY, or leave both unset
GOATCOUNTER_URLunsetOrigin of a GoatCounter instance, such as https://stats.example.com, to count page views in the web app. Only route names are sent (/library, /bookmarks/$id), never ids, search terms or titles; no cookies; browsers with Do Not Track or Global Privacy Control are not counted. Added to the CSP's connect-src. Must be https (http only on localhost) with no path. Unset, nothing is counted
REQUIRE_VERIFIED_EMAILfalseWhen true and mail is on, the verified-email hard gate applies even if the admin toggle is off. The admin UI shows the toggle on and disabled
BLOCK_DISPOSABLE_EMAILSfalseWhen true, registration and email-change refuse addresses on an embedded disposable-domain list (400 "Use a lasting email address.")

The API refuses to start when only one Turnstile key is set.

Single sign-on​

Each provider is on when its variables are all set, and gets its own button on the sign-in page, in this order. Details and how SSO meets existing password accounts: Single sign-on.

VariableWhat it does
OIDC_ISSUERAny OpenID Connect provider (Authentik, Keycloak, …). Issuer exactly as the provider's /.well-known/openid-configuration reports it, trailing slash included. Authentik: https://auth.example.com/application/o/<slug>/
OIDC_CLIENT_IDClient ID from the provider
OIDC_CLIENT_SECRETClient secret from the provider
OIDC_NAMEName on its button, such as Authentik. Default: "single sign-on"
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRETGoogle sign-in (an OAuth client of type "Web application" in Google Cloud)
MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_IDMicrosoft Entra ID sign-in for one tenant. The tenant is the directory (tenant) ID, a GUID; common, organizations and consumers are refused because their issuer cannot be checked
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRETGitHub sign-in (a GitHub OAuth app)

Register {APP_URL}/api/auth/oidc/callback as the redirect URI with every provider. A new identity gets an account only while registration is open. The API refuses to start when a pair or the Microsoft triple is only partly set.

Passkeys need no variables. They belong to the host in APP_URL: changing that host strands every passkey, and browsers allow them only over https:// (or http://localhost).

Screenshots​

VariableDefaultWhat it does
BROWSER_WS_URLunsetChrome DevTools address, http://chrome:9222 with the service above. Unset, no screenshots are taken
BROWSER_PROXY_BINDunsetAddress the API serves Chrome's egress proxy on, 0.0.0.0:3128 with the service above. Only starts when BROWSER_WS_URL is set too. The proxy connects only to public addresses, and only to ports 80, 443 and 1024 and up. The API refuses to start if the value is not address:port

Logging​

VariableDefaultWhat it does
LOG_FORMATtexttext for human stdout, json for one JSON object per line on stdout. Invalid values stop startup
LOG_FILEunsetWhen set, append JSON lines (JSONL) to this path even if stdout stays text. Create the file if missing; open failures stop startup. Rotate the file yourself (for example logrotate); the process does not
RUST_LOGinfoLog filter, such as debug or info,linkdean_api=debug (also listed under Advanced)

Every HTTP response includes X-Request-Id. A valid inbound value (1–128 characters: letters, digits, _, -, .) is kept; otherwise the API mints a UUID. The same id appears on the request's log span.

Metrics​

VariableDefaultWhat it does
METRICS_TOKENunsetTurns on GET /api/metrics (Prometheus format), which then needs Authorization: Bearer <token>. Unset, the route returns 404

Tracing​

Off unless an endpoint is set. Details: Tracing.

VariableDefaultWhat it does
OTEL_EXPORTER_OTLP_ENDPOINTunsetBase URL of an OpenTelemetry collector that takes OTLP over HTTP (protobuf), such as http://otel-collector:4318. Spans go to <endpoint>/v1/traces. Set, the API exports a span per request
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTunsetFull traces URL instead of the base one
OTEL_EXPORTER_OTLP_HEADERSunsetHeaders for the collector, such as x-honeycomb-team=<key> or Authorization=Basic <base64> (comma-separated name=value)
OTEL_SERVICE_NAMElinkdean-apiService name on every span
OTEL_TRACES_SAMPLERparentbased_always_onalways_on, always_off, traceidratio or the parentbased_ forms
OTEL_TRACES_SAMPLER_ARG1.0Ratio for the traceidratio samplers, such as 0.1 for one request in ten

A background worker checks saved links and flags dead ones under Library health. Vault bookmarks and private hosts are skipped.

VariableDefaultWhat it does
LINK_CHECK_ENABLEDtrueSet false to turn the checker off
LINK_CHECK_TICK_SECS60Seconds between rounds
LINK_CHECK_BATCH_SIZE40Links checked per round
LINK_CHECK_CONCURRENCY2Links checked at once
LINK_CHECK_PER_HOST_DELAY_MS1000Pause between two requests to the same host
LINK_CHECK_RECHECK_DAYS7Days before a checked link is checked again

Experimental features​

Off by default. They may change or go away between releases.

VariableDefaultWhat it does
EXPERIMENTAL_AGENT_SKILLSfalsetrue turns on Agent Skills: GET /api/agent-skill, the Agent Skill card under Import / Export and the folder menu item. Off, the route answers 404 and the app hides both

Advanced​

These have working defaults inside the image. Change them only for a reason.

VariableDefaultWhat it does
SESSION_DAYS30Days a sign-in lasts
CORS_ORIGINSAPP_URLComma-separated browser origins allowed to call the API. * allows any origin; avoid it on a reachable server
RUST_LOGinfoLog filter, such as debug or info,linkdean_api=debug
BIND0.0.0.0:8080Listen address inside the container. If you change the port, change ports: and the healthcheck too
DATABASE_URLset by the compose filePostgres connection string. Set it in .env only to use your own Postgres server, and remove DATABASE_URL from the compose file's environment: so yours is used
MEILI_URLset by the compose fileMeilisearch address
AVATAR_DIR/app/data/avatarsWhere uploaded avatars are stored. Keep it on the avatars volume
PREVIEW_DIR/app/data/previewsWhere screenshots and cached favicons and Open Graph images are stored. Keep it on the previews volume
STATIC_DIR/app/staticBuilt web app served by the API

Never in production​

VariableWhat it does
ALLOW_DEFAULT_SECRETSLets the API start on the secrets published in this repository and turns on development-only routes. For local development only