Skip to main content

Operations

This page covers production operations for the Compose stack in deploy/docker/docker-compose.yml and for released-image installs. Published copy: docs.linkdean.app. To install a released image, start with quick-start.md. Full variable reference: environment.md. For local development, see Development setup below and the README.

Quick start​

git clone https://github.com/arsamsarabi/linkdean.git
cd linkdean
printf 'POSTGRES_PASSWORD=%s\nMEILI_MASTER_KEY=%s\nSESSION_SECRET=%s\n' \
"$(openssl rand -hex 32)" "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > deploy/docker/.env

docker compose --env-file deploy/docker/.env -f deploy/docker/docker-compose.yml up -d --build

Open http://localhost:8080. The first registered user becomes admin. Set BOOTSTRAP_TOKEN (see First account) when the server is reachable by others before you register.

  1. Create deploy/docker/.env with the required secrets and set APP_URL. Behind a reverse proxy, also set TRUST_FORWARDED_FOR=true (see Reverse proxy).
  2. Compose up (command above).
  3. On first visit, register (bootstrap admin).
  4. Optional OIDC: set issuer, client id, and secret. OIDC_ISSUER is the provider's issuer exactly as its /.well-known/openid-configuration reports it, trailing slash included (Authentik: https://auth.example.com/application/o/<slug>/). Callback: {APP_URL}/api/auth/oidc/callback. OIDC sign-in obeys closed registration: an unknown identity gets no account unless registration is open. See Single sign-on for how it meets existing password accounts.
  5. Avatars persist in the avatars volume (AVATAR_DIR); screenshots + favicon/OG binaries in previews (PREVIEW_DIR). Include both with Postgres backups.

Secrets are injected via environment variables (or the operator's preferred secret store). No Infisical dependency. deploy/docker/.env is gitignored; keep it out of version control.

Prebuilt image​

Each v* tag publishes ghcr.io/arsamsarabi/linkdean:<version> to the GitHub Container Registry. To run it without cloning or building, follow quick-start.md: it has the Compose file to copy and the optional Chrome setup. Every environment variable is in environment.md.

Production deployment​

Required secrets​

The production Compose file refuses to start without POSTGRES_PASSWORD, MEILI_MASTER_KEY, and SESSION_SECRET. Generate each with openssl rand -hex 32. Full descriptions: environment.md.

Without one of them, docker compose up stops with set POSTGRES_PASSWORD (or the matching name).

The API also refuses to start when a secret is a value published in this repository: the .env.example and dev Compose defaults for SESSION_SECRET and MEILI_MASTER_KEY, and the linkdean:linkdean database login. Generate your own values. ALLOW_DEFAULT_SECRETS=true turns this check off; it exists for local development only and must never be set in production.

First account​

The first account on an empty instance becomes admin. Sign-ups are serialised, so two people registering at once cannot both become admin, but without a token whoever registers first owns the instance.

Set BOOTSTRAP_TOKEN to a long random string (openssl rand -hex 32) to require it for that first account. The setup page asks for it. With a token set, the first account must register with a password: an OIDC sign-in cannot carry the token and is refused until an admin exists. Once any account exists the token is ignored and you can remove it.

Per-user quotas​

Under Admin → Quotas, optional caps apply to every account (leave blank for unlimited):

  • Max bookmarks (owned, not deleted). An import that would exceed the cap is refused entirely.
  • Max stored image bytes (avatar + preview/favicon/OG files on disk).
  • Max enrich actions per UTC day (page HTML, favicon, OG and screenshot fetches).
  • Max import payload bytes (cannot exceed the 10 MiB hard cap).
  • Max uploaded image bytes (cannot exceed the avatar/preview hard caps).

When a cap is hit the API answers 403 with {"code":"quota_exceeded","meter":…}. Users see current usage under Settings → General when any limit is set. Membership plans are not wired yet; limits go through one resolver so plans can plug in later.

Failed screenshots​

A screenshot that times out, common right after a large import, leaves the bookmark on its Open Graph image or favicon. Linkdean retries failed screenshots on its own once they are older than the automatic retry window (7 days by default), in a check that runs at start and every 6 hours.

To retry sooner, open Admin → Screenshots and press Retry failed screenshots. It shows how many would be retried, takes them two at a time, and can be used once per cooldown (24 hours by default). It only retries screenshots that failed longer ago than the cooldown, so pages that just failed are left alone. Both the cooldown and the automatic window are set in the same panel.

Reverse proxy​

Login, registration and vault-unlock limits count attempts per client address. By default the API uses the address of the TCP connection.

  • Behind a reverse proxy (Caddy, nginx, Traefik, a tunnel): set TRUST_FORWARDED_FOR=true. Otherwise every request appears to come from the proxy, all users share one counter, and a few failed logins from anyone block logins for everyone. On HTTPS, set HSTS_MAX_AGE (for example 31536000) or configure HSTS on the proxy/CDN; leave it unset on plain HTTP so browsers are not stuck requiring HTTPS for localhost.
  • API reachable directly: leave TRUST_FORWARDED_FOR unset. With it on, a client can forge X-Forwarded-For and pick any address, which defeats the per-address limits.

Only enable it when the proxy is the sole route to the API, and make sure the proxy appends the client address to X-Forwarded-For. The API reads the last entry, the one your proxy wrote. With a chain of proxies, the last entry is the nearest proxy's view, so terminate the chain at a single proxy in front of the API.

A Cloudflare Tunnel in front of Caddy is such a chain: Caddy sees the cloudflared container as the client and writes that address, so every user still shares one counter. Tell Caddy to trust the tunnel's network, take the client from Cf-Connecting-Ip, and pass on only that address:

{
servers {
trusted_proxies static 10.89.12.0/24 # the network cloudflared and Caddy share
client_ip_headers Cf-Connecting-Ip
}
}

links.example.com {
reverse_proxy api:8080 {
header_up X-Forwarded-For {client_ip}
}
}

A request from any other peer keeps its TCP address, so a forged Cf-Connecting-Ip header has no effect. deploy/public-beta/Caddyfile uses this setup.

Container runtime​

  • The API image runs as an unprivileged user, linkdean (UID/GID 10001). It owns /app/data/avatars and /app/data/previews; the binary and static files stay read-only to it.
  • Every service uses restart: unless-stopped, so the stack comes back after a crash or host reboot.
  • Only api publishes a port (8080). Postgres, Meilisearch and Chrome stay on the Compose network.
  • Chrome (chromedp/headless-shell, pinned) takes page screenshots for bookmark previews, so it opens every page users save. It sits on its own browser network with the API and has no route to Postgres or Meilisearch. That network is internal, so Chrome's only way to the web is the API's egress proxy (BROWSER_PROXY_BIND), which refuses private addresses. WebSockets, service workers and DNS rebinding cannot take a page to the LAN. It runs as nobody with a read-only filesystem, no capabilities, no-new-privileges, 1 GB of memory and 512 processes, and with Chrome's own sandbox on.
  • That sandbox needs user namespaces, which Docker's default seccomp profile blocks. deploy/docker/chrome-seccomp.json is Docker's default profile plus clone, unshare, setns and chroot, and must sit next to the compose file. Some hosts also restrict unprivileged user namespaces through AppArmor (Ubuntu 23.10 and later). There Chrome exits with No usable sandbox! in its logs, and bookmarks fall back to OG images and favicons. Allow it persistently, with the trade-off and how to undo it, as in Hosts that restrict user namespaces, or leave BROWSER_WS_URL unset to run without screenshots.
  • Update the Chrome image tag with each stable Chrome release.

Limits and behaviour operators should know​

AreaBehaviour
Failed logins10 per address per account, 50 per address, 50 per account, each per 15 minutes. Past a limit the API returns 429 until the window ends. A successful login clears only the per-address-per-account counter
Account lockout50 failed logins on one account from any address lock that account for 15 minutes, including the correct password. Someone who knows a user's email can trigger this on purpose
Registration10 attempts per address per 15 minutes, counted whether or not they succeed
Email verification and changeEmails: 3 per account and 10 per client IP. Link uses: 10 per client IP. Each per 15 minutes
Share invite emails20 per owner per hour. Past that the share is still created without an email, and the owner is told none was sent
Vault unlock, recovery, global unlock, recovery key replacement, global passphrase off10 failed attempts per user per 15 minutes, shared across all of these
Limit storageCounters live in API memory. Restarting the API resets them, and several API replicas would each keep their own
Not limited yetPassword change and global vault passphrase change
Password hashingArgon2id at 64 MiB and 3 passes per hash or vault key unwrap. At most 4 run at once (up to 256 MiB); extra logins queue. Older, cheaper password hashes are upgraded at the next sign-in
Passwords and vault passphrasesNew ones need at least 12 characters. Existing shorter ones still work
Expired sessionThe API returns 401 with {"code":"session_expired"}, and the web app signs the user out and opens /login. A wrong password stays a plain 401
Database queriesEach statement times out after 30 seconds. Migrations run without this limit
ImportRequest body up to 20 MiB; file content up to 10 MiB; folders nested at most 64 deep; at most 10,000 folders per import. Folder loops are refused
Avatar uploadRequest body up to 6 MiB (larger uploads currently fail with 400, not 413)
Preview uploadRequest body up to 9 MiB
Image decode (avatar, preview)At most 40 megapixels and 160 MiB of decode memory per image; two decodes run at once and the rest wait
Trash retentionUser setting from 1 to 3,650 days, enforced by a database CHECK

Email​

Mail is optional. Without it the instance runs as before and sends nothing. Set SMTP_HOST and MAIL_FROM (and the related SMTP variables) on the api service — see environment.md. The production Compose file passes them through.

The API refuses to start when:

  • only one of SMTP_HOST and MAIL_FROM is set
  • only one of SMTP_USERNAME and SMTP_PASSWORD is set
  • SMTP_TLS is not starttls, tls or none, or SMTP_PORT is not a port number
  • MAIL_FROM is not a valid mailbox
  • SMTP_TLS=none is set for a host that is not local. none sends mail unencrypted, so it is allowed only for localhost, loopback and private addresses, and single-label names such as mailpit. A single-label name can still resolve through your DNS search domain, so use none only on a network you control

Examples:

  • Gmail: SMTP_HOST=smtp.gmail.com, port 587, STARTTLS (the default). Use an app password, which needs 2-Step Verification on the account. MAIL_FROM must be the Gmail address or a verified alias.
  • Fastmail: SMTP_HOST=smtp.fastmail.com, SMTP_TLS=tls (port 465), with an app password.
  • Postmark: SMTP_HOST=smtp.postmarkapp.com, port 587. SMTP_USERNAME and SMTP_PASSWORD are both the server API token, and the MAIL_FROM address needs a verified sender signature.

Check it works: Admin → Email → Send test email. The panel shows the settings in use (never the username or password), sent, queued and failed counts for the last 24 hours, and the latest error. The test goes straight to SMTP, skipping the queue, to the admin's own address, and shows the server's answer. Each admin can send 5 tests per 15 minutes.

Delivery:

  • Email is queued in Postgres and sent in the background by the API. A failed send is retried after 30 seconds, then at doubling intervals up to an hour apart. An email still unsent a day after it was queued is marked failed.
  • Each SMTP step times out after 20 seconds, and a whole send after 60.
  • Sent emails are deleted after 7 days and failed ones after 30.
  • Delivery is at least once: if the API stops after the server accepted an email but before it was marked sent, it is sent again.

SPF, DKIM and DMARC are set up with your mail provider and DNS, not in Linkdean.

Password reset:

  • With mail on, the login page links to Forgot password?. The emailed link works once, for 30 minutes. Links are built from APP_URL, so set it to the address people open Linkdean at.
  • With mail off, the login page tells people to ask an admin. An admin opens Admin → Accounts, picks the user and chooses Reset link. The link is shown once, works once, for 24 hours, and must be sent privately: anyone with it can set the password. With mail on, the user is also told by email that an admin made one.
  • A new link voids the previous one, and so does a normal password change. A reset ends every session, signs in the browser that reset, and leaves every vault locked; vault passphrases do not change.
  • Accounts that sign in only with OIDC have no password to reset. They get an email saying so, and the admin link is refused for them.
  • Each email address can request 3 links per 15 minutes, and each client IP 10. Each client IP can try 10 links per 15 minutes.

Email verification:

  • Verification needs mail. With mail on, a password registration sends a link to the new address, and unverified accounts see a banner with Resend email. The link works once, for 24 hours, and a new one voids the previous one. Opening it verifies the address without signing in.
  • OIDC accounts count as verified when the identity provider reports the address as verified.
  • A folder or dashboard share to an unverified account does not reach it. The invite waits for the address and attaches when the account verifies, after which the account still accepts it as usual.
  • With mail off, new accounts stay unverified, there is no banner, and invites to them wait as pending invites. The invite's claim link still works, now also while signed in, when the signed-in account's address matches the invite. An admin can also mark the account verified.
  • People change their own address under Profile → Edit profile → Change email, with their current password. The link goes to the new address and the old one gets a notice; the address only changes when the link is opened. Accounts that sign in only with OIDC cannot change it here. With mail off the option says to ask an admin.
  • Admin → Accounts has Mark verified, Remove verification and Change email for each account. An admin email change applies at once and counts as verified. Removing verification keeps shares already accepted; only new invites wait.
  • Require verified email under Admin holds unverified accounts at a verify screen with Resend email and Sign out, and the API answers 403 with {"code":"email_unverified"} on every route outside /api/auth/. It can only be turned on while mail is on, and it never applies to admins, so it cannot lock everyone out. If you turn mail off while it is on, the gate stops applying until mail is back. Host env REQUIRE_VERIFIED_EMAIL=true forces the same gate (OR with the setting) and shows the toggle on and disabled.
  • Turnstile (TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY, both or neither): password registration shows Cloudflare Turnstile and the API verifies the token; OIDC is unchanged. Unset, registration works as before.
  • Disposable emails (BLOCK_DISPOSABLE_EMAILS=true): registration and email-change refuse addresses on an embedded throwaway-domain list with 400 "Use a lasting email address."
  • Each account can send 3 verification or email change emails per 15 minutes, and each client IP 10. Each client IP can try 10 verification or email change links per 15 minutes.
  • Upgrading: every account that exists when you upgrade counts as verified (migration 042). If you do not trust an account's address, remove its verification under Admin → Accounts.

Share invites and notifications:

  • With mail on, sharing a folder or dashboard emails the invitee. A verified account gets an invite that links to Linkdean's Shared page. An address with no account, or an unverified one, gets the claim link (APP_URL/register?share=…), which also works while signed in. The owner still sees that link to copy. Nothing is emailed for an access change, or to someone who declined an earlier invite from the same owner.
  • Each owner can send 20 invite emails per hour. Past that the share is still created, and the owner is told no email was sent and to copy the link instead. The count lives in API memory, like the other limits, so a restart resets it.
  • People choose which notifications they also get by email under Settings → Notifications. Share invites and moderation changes to their public content are on by default; access changes, revoked shares, edits in shared folders, likes, comments, ratings and new followers are off. Each kind can also be set to a daily digest, sent after 8:00 in the person's profile time zone (UTC when none is set). Only verified addresses get them, the in-app block and mute rules still apply, and every email ends with a link to that settings page and a signed one-click unsubscribe link (also in List-Unsubscribe headers). Changing SESSION_SECRET voids the unsubscribe links in emails already sent.
  • With mail off, notifications stay in the app only and nothing waits to be sent: turning mail on later does not send old notifications. The settings tab says email notifications need outbound email.

Single sign-on​

Turn on any mix of a generic OpenID Connect provider, Google, Microsoft and GitHub (see environment). An account holds one provider identity at a time; to switch, disconnect the old one first.

  • Google and Microsoft are OpenID Connect issuers like any other. Microsoft works for one tenant (MICROSOFT_TENANT_ID); personal Microsoft accounts and multi-tenant apps are not supported yet.
  • GitHub is OAuth only. Linkdean reads the numeric user id (stable across renames) and the primary email when GitHub marks it verified, otherwise the first verified one; an account with no verified email is refused. Identities are stored with the issuer https://github.com. GitHub cannot be asked for a fresh sign-in, so for an account that signs in only with GitHub, the step-up before deleting it or adding a passkey is a plain GitHub round trip.
  • Passkeys sign in without a password or email. Adding one needs the current password, or a fresh single sign-on for an account without one, and emails the account. The passkey's user handle is the account id, and the API keeps the challenge server side for 5 minutes, single use.

Accounts are matched to the identity provider by issuer and subject, never by email alone. When an OIDC sign-in brings an address that a password account already uses:

  • The login page says "An account already uses x•••@example.com. Sign in with its password to connect single sign-on." Signing in with that account's password attaches the provider identity to it and shows Single sign-on connected. From then on the provider alone signs in.
  • The waiting link lives on the server for 10 minutes and is tied to the browser by an HttpOnly cookie (linkdean_oidc_link); nothing identifying goes in the URL. It is used up by the next password sign-in in that browser, whether or not it linked. Nothing links when the password is wrong, the link expired, or the password belongs to a different account than the one holding the provider's address. The usual login limits apply.
  • The account's address gets a "Single sign-on was connected" email (when mail is on), so a link nobody expected can be undone by resetting the password and telling the admin.
  • Linking marks the account verified only when the provider reports that same address as verified.
  • If the person does not know the account's password, the page says to ask the admin. An admin can reset that account's password, or change its address under Admin → Accounts → Change email, which frees the address for a normal single sign-on.
  • An account that signs in only with OIDC, or that is already connected to a different identity, is not linked: the login page says why.

Signed-in people manage it under Profile → Edit profile → Single sign-on (shown when OIDC is configured):

  • Connect runs the provider sign-in and attaches that identity to the signed-in account, even when the provider's address differs. The account's address stays as it is.
  • Disconnect needs the current password and is only offered to accounts that have one, so nobody loses their only way to sign in. Wrong passwords count against the login limits.
  • One provider identity belongs to at most one account, and an account has at most one identity. Connecting an identity already attached elsewhere is refused: "This sign-in is already connected to another account."
  • Deleting an SSO-only account asks the person to sign in again with the provider first. Linkdean sends prompt=login and max_age=0 and accepts the answer only for the identity already attached and only when the ID token's auth_time is under 5 minutes old, so the provider must include auth_time (the OIDC spec requires it when max_age is sent; Authentik and Keycloak do). The step-up lasts 10 minutes, in that browser session only.

API clients​

The API is described by an OpenAPI 3.1 document at GET /api/openapi.json on every instance, rendered as the API reference. Errors share one body, { "code", "message", "details"?, "error" }; match on code. JSON reads carry an ETag, and If-None-Match with it answers 304.

The browser extension (apps/extension) signs in to any instance: people type its address in the extension, approve it on /connect/extension, and the extension gets an API key. That needs API keys enabled, platform-wide and for the account (Admin). The extension asks the browser for access to the instance's host only. Self-hosted instances must be served over https://; plain http:// works only for localhost.

PATCH bodies distinguish a missing field from null:

  • Field omitted → left unchanged.
  • Field set to null → cleared. This applies to profile display_name, bio and timezone; bookmark description, notes and category_id; and category parent_id (moves the category to the root) and icon.

Scripts written against older builds that sent null to mean "no change" will now clear those fields.

Upgrading an existing install​

Earlier builds ran as root with a default database password. Before upgrading past commit bdef6d8:

  1. Database password. Postgres sets its password only when the db volume is first created, so a new POSTGRES_PASSWORD does not change an existing database. If the database still uses linkdean, change it to match your new value before starting the new api:

    docker compose -f deploy/docker/docker-compose.yml exec db \
    psql -U linkdean -d linkdean -c "ALTER USER linkdean PASSWORD '<new POSTGRES_PASSWORD>'"

    The API refuses the old linkdean:linkdean login, so skipping this step stops it at startup.

  2. Meilisearch key. A new MEILI_MASTER_KEY takes effect when Meilisearch restarts. If search is empty afterwards, run Admin → Reindex search.

  3. Volume ownership. Files written by the old root container stay owned by root, and the new UID 10001 process cannot write them. Fix once:

    docker run --rm -v linkdean_avatars:/avatars -v linkdean_previews:/previews alpine \
    chown -R 10001:10001 /avatars /previews
  4. Migrations run on API start. Migration 034 caps trash retention at 3,650 days and clamps larger values. Migration 035 removes decrypted vault titles from old activity entries. Migration 042 marks every existing account's email verified; see Email.

  5. Reverse proxy. Set TRUST_FORWARDED_FOR=true if you run behind one.

Development setup​

The dev stack (deploy/docker/docker-compose.dev.yml) and .env.example use well-known secrets and set ALLOW_DEFAULT_SECRETS=true, so they start without generating anything. Never copy those values into production.

The dev and production Compose files share a project name and volumes. Run one at a time. A database volume first created by the dev stack keeps the password linkdean; follow Upgrading an existing install step 1 before switching that volume to production.

Running the API and web on the host is covered in the README under Development.

Tracing​

Set OTEL_EXPORTER_OTLP_ENDPOINT (see environment) and the API sends one span per request to that collector over OTLP/HTTP. Anything that takes OTLP works: an OpenTelemetry Collector, Jaeger, Grafana Tempo, Honeycomb, Grafana Cloud.

  • Each span is named by the HTTP method and carries request_id (the X-Request-Id header, also in the logs), http.request.method, url.path and http.response.status_code. 5xx answers mark the span as an error.
  • Only the path is recorded, never the query string, since queries can hold search terms. Bodies, headers and user ids are not recorded.
  • Spans are batched and sent in the background; the API flushes what is left when it stops. A collector that is down costs nothing but the lost spans.
  • To find one request, take the X-Request-Id from a response or a log line and search the tracing backend for request_id.

Healthchecks​

ProbePathMeaning
LivenessGET /api/healthProcess up; the body reports the running version
ReadinessGET /api/readyPostgres + Meilisearch reachable
MetricsGET /api/metricsPrometheus scrape. Off unless METRICS_TOKEN is set; then send Authorization: Bearer <token>

/api/ready returns true or false per check. Failure details go to the API log, not the response.

Metrics are labelled by route template (such as /api/l/{slug}), never by raw path.

Compose marks db, meilisearch, and api healthy before dependents start. Example:

curl -fsS http://localhost:8080/api/health
curl -fsS http://localhost:8080/api/ready

Backup​

The managed public beta on Nova uses restic to a dedicated Backblaze B2 bucket, with Infisical as the env SoT — see deploy/public-beta/BACKUP.md.

For a self-hosted Compose install, stop writes briefly (or accept a short inconsistency window), then dump Postgres + Meili + volumes:

# from deploy/docker (compose project name: linkdean)
set -a; . ./.env; set +a
COMPOSE="docker compose -f docker-compose.yml"

# 1. Postgres
$COMPOSE exec -T db pg_dump -U linkdean -d linkdean -Fc > "linkdean-pg-$(date +%F).dump"

# 2. Meilisearch dump (creates a dump task; file lands under meili volume)
$COMPOSE exec -T meilisearch \
wget -qO- --header="Authorization: Bearer ${MEILI_MASTER_KEY:?}" \
--post-data='' http://127.0.0.1:7700/dumps
# After the dump task completes, copy from the meili volume, e.g.:
# docker run --rm -v linkdean_meili:/data -v "$PWD":/out alpine \
# sh -c 'cp /data/dumps/*.dump /out/'

# 3. File volumes (avatars + previews)
docker run --rm \
-v linkdean_avatars:/avatars \
-v linkdean_previews:/previews \
-v "$PWD":/out alpine \
tar czf /out/linkdean-files-$(date +%F).tgz -C / avatars previews

Restore Postgres with pg_restore into a fresh DB, restore Meili dump per Meilisearch dump docs, then extract the files tarball back onto the named volumes and run the chown from Upgrading step 3 if the tarball was made as root. After restore, use Admin → Reindex search if the Meili dump was skipped.

Data volumes​

Four named volumes hold everything: pgdata (Postgres), meili (search index, which can be rebuilt from Admin → Reindex search), avatars and previews. Back up pgdata, avatars and previews. docker compose down keeps them; docker compose down -v deletes them.