Environment Variables

A quick-reference for every environment variable used by LinkDen.

Quick Start

cp .env.example .env

LinkDen uses a single .env file at the monorepo root. Five variables are required to run the app; a few more are needed to deploy it.

Required Variables

In production these are all the same hostname. LinkDen runs same-origin: the web Worker owns SITE_DOMAIN and the API Worker is routed under it at /api/* and /trpc/*. So with SITE_DOMAIN=links.yourdomain.com:

BETTER_AUTH_URL=https://links.yourdomain.com
NEXT_PUBLIC_SERVER_URL=https://links.yourdomain.com
CORS_ORIGIN=https://links.yourdomain.com
NEXT_PUBLIC_SITE_URL=https://links.yourdomain.com

Locally the web app (:3001) and API (:3000) are different origins, which is why the local examples differ.

Deploy-time validation

bun ship (and the GitHub deploy) refuses to start, before touching any Cloudflare resource, when:

• any of the five required variables is empty or has surrounding whitespace (an unset GitHub secret arrives as an empty string);
• BETTER_AUTH_SECRET is shorter than 32 characters or is Better Auth's public default;
• BETTER_AUTH_URL, CORS_ORIGIN, NEXT_PUBLIC_SERVER_URL or NEXT_PUBLIC_SITE_URL is not an https:// URL;
• CORS_ORIGIN is more than a bare origin (no path, no trailing slash);
• SITE_DOMAIN is set and BETTER_AUTH_URL, CORS_ORIGIN or NEXT_PUBLIC_SITE_URL is not exactly https://SITE_DOMAIN.

A deploy reads the root .env (or the CI environment) only. apps/web/.env and apps/server/.env are loaded by bun dev alone and are never read by a deploy.

Cloudflare Deployment

Only needed when deploying with bun ship or the GitHub Actions deploy workflow:

Runtime Configuration

Most settings that were previously environment variables are now managed through the admin UI at /admin/settings and stored in the database:

This keeps the .env file minimal and lets you change settings without redeploying.

Apple Wallet (Optional)

Only required if you want to generate Apple Wallet passes. All five values are needed together — if any one is missing, pass downloads answer 503 and Settings → Wallet shows what is missing. You can also upload the same material in Settings → Wallet instead; a value saved there overrides the environment variable.

Certificates and the key can be raw PEM, base64 of the PEM (one line, easiest for .env and GitHub secrets), or, for certificates, base64 of a DER .cer file. The key must be an RSA key (PKCS#1 or PKCS#8); EC keys and .p12 bundles are not supported.

These are secrets — keep them in .env locally or in GitHub environment secrets. Never commit them to git.

See the Apple Wallet guide for step-by-step certificate setup.

Complete .env Example

# Required
BETTER_AUTH_SECRET=your-generated-secret-key
BETTER_AUTH_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3001
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
NEXT_PUBLIC_SITE_URL=http://localhost:3001

# Cloudflare deployment only
# CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
# CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
# ALCHEMY_PASSWORD=your-generated-state-secret
# ALCHEMY_STATE_TOKEN=your-state-worker-token
# ALCHEMY_STAGE=prod
# SITE_DOMAIN=links.yourdomain.com
# SETUP_TOKEN=your-generated-setup-token
# LINKDEN_CONFIRM_DESTROY_PROD=yes   # only when you really mean to destroy prod

# Apple Wallet (optional — all 5 required together)
# WALLET_SIGNER_CERT=base64-of-signer_cert.pem
# WALLET_SIGNER_KEY=base64-of-signer_key.pem
# WALLET_WWDR_CERT=base64-of-AppleWWDRCAG4.cer
# WALLET_SIGNER_KEY_PASSPHRASE=only-if-the-key-is-encrypted
# WALLET_TEAM_ID=ABC12DEF34
# WALLET_PASS_TYPE_ID=pass.com.yourname.linkden

Setting Variables

Alchemy binds these to the Workers at deploy time from your .env (local bun ship) or from the GitHub production environment (deploy.yml). In GitHub, store SITE_DOMAIN, NEXT_PUBLIC_SITE_URL (and LINKDEN_DB_NAME / LINKDEN_IMAGES_BUCKET if you need them) as variables and everything else as secrets. Values set by hand in the Cloudflare dashboard are overwritten on the next deploy.

First-Time Setup

After deployment, navigate to /admin/setup to create your admin account. The first user becomes the admin and registration locks automatically (a database trigger enforces a single admin). Until then the setup page is open to anyone who finds it, so on a public deploy set SETUP_TOKEN and enter it in the wizard's Setup token field.

Local development only

Troubleshooting

CORS errors

CORS_ORIGIN must exactly match the web app URL — including protocol (https://), no trailing slash. In production it equals https://SITE_DOMAIN.

Authentication not working

• Verify BETTER_AUTH_SECRET is set (32+ characters); /api/health shows "auth": "misconfigured" otherwise
• Verify BETTER_AUTH_URL matches the URL the browser actually reaches the API on (https://SITE_DOMAIN in production)
• If you are on workers.dev, the web and API Workers are different origins and the session cookie cannot cross them. Set SITE_DOMAIN and redeploy

Changes not taking effect

• NEXT_PUBLIC_SERVER_URL and NEXT_PUBLIC_SITE_URL are baked into the frontend at build time. Changing either requires a redeploy (bun ship rebuilds).
• Server-side variables take effect on the next request after a redeploy.