Environment and Configuration

This page is the source of truth for required env vars in the current repo.

Runtime public config now uses PUBLIC_* names. The legacy NEXT_PUBLIC_* names are still accepted as fallbacks for compatibility, but only PUBLIC_AUTH_PROVIDER is a build-time variable used to choose the auth provider bundle.

Code references:

• web schema: apps/ship/src/env.ts
• auth runtime: packages/auth/src/server.ts, packages/auth-clerk/src/server.ts
• api runtime: apps/ship-api/src/server.ts and apps/ship-api/src/index.ts
• Trigger runtime sync: apps/ship-api/trigger.config.ts
• Docker build: Dockerfile, .github/workflows/publish-ghcr.yml

Environment Ownership Matrix

Classify env vars by who reads them first. Do not mix build inputs, container runtime env, and Trigger runtime env.

Minimum Required (Web + API)

Without these variables, startup or core auth/payment/storage flows will break.

Upload Provider Selection

The shared S3_* variables above are the baseline storage config. Better Upload server routes can also select a provider dynamically from settings, then fall back to env. This is a server-side configuration mechanism, not an end-user provider switcher UI.

Provider resolution order:

1. UPLOAD_PROVIDER_OVERRIDES[userId] in the settings table
2. UPLOAD_PROVIDER_DEFAULT in the settings table
3. BETTER_UPLOAD_PROVIDER
4. cloudflare

Credentials and client fields are resolved from the client object in settings first, then from env aliases such as AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY and S3_ACCESS_KEY / S3_SECRET_KEY. Configure path-style or provider-specific client behavior in the settings client object, not as a global env variable.

Better Auth only (when PUBLIC_AUTH_PROVIDER=better-auth)

Clerk only (when PUBLIC_AUTH_PROVIDER=clerk)

API Runtime / Deployment Variables

The mounted API route prefix still depends on the entrypoint:

• Next.js ship route surface: /api/v1/*
• Standalone ship-api service: /v1/*

When PUBLIC_SERVER_URL is omitted, the web app talks to the same-origin /api/v1 surface under SITE_URL. Set it only when the browser-facing API origin differs from SITE_URL. With VERCEL_ENV present, browser requests use ${PUBLIC_SERVER_URL}/api/v1; without VERCEL_ENV, they use ${PUBLIC_SERVER_URL}/v1 for standalone ship-api or Worker-style API origins.

Production Address Variables

Use this table when updating Infisical, container runtime env, or host-level env.

GitHub Variables for Infisical OIDC (GHCR Docker Build)

Add these values as GitHub Repository Variables, not source code. Entry: GitHub repo > Settings > Secrets and variables > Actions > Variables > New repository variable.

These variables are for the Load Infisical secrets step in publish-ghcr.yml. They only let GitHub Actions locate the Infisical project/env/folder through OIDC; they are not business runtime secrets. Trigger deploy does not need this Infisical OIDC set.

publish-ghcr.yml already declares permissions.id-token: write, so OIDC auth method not found for identity usually does not mean GitHub Actions cannot issue an OIDC token. It means the Infisical identity referenced by INFISICAL_IDENTITY_ID does not have OIDC Auth configured. A newly created machine identity may default to Universal Auth; for GitHub Actions, remove/replace Universal Auth with OIDC Auth.

Troubleshooting order:

1. OIDC auth method not found for identity: open the INFISICAL_IDENTITY_ID identity from Project > Access Control > Machine Identities and confirm Authentication includes OIDC Auth. If it still uses Universal Auth, remove/replace it with OIDC Auth.
2. Subject mismatch: this workflow uses GitHub Environments, so the production branch subject is repo:<owner>/<repo>:environment:Production, not repo:<owner>/<repo>:ref:refs/heads/main.
3. Folder with path '/' ... was not found: INFISICAL_ENV_SLUG or INFISICAL_SECRET_PATH does not match Infisical. If the folder is env under the root, set INFISICAL_SECRET_PATH=/env.

Workflow entry points:

GHCR Build Inputs

The private GHCR image is built by .github/workflows/publish-ghcr.yml using Dockerfile. The workflow builds a Better Auth image under the default tags (latest, branch tag, <branch>-<sha>) and a Clerk image under clerk-latest / clerk-<sha>. Runtime env and runtime public config are injected by the running container, so the same provider-specific image can be reused across environments.

Build args:

BuildKit secret file: the workflow writes the Infisical output to .infisical.docker.env and passes it to Docker build as infisical_env. The Dockerfile only reads that file during the build; it is not copied into image layers. Use it only for build-time/public config such as VERCEL_ENV or PUBLIC_*. The Docker build sets SKIP_ENV_VALIDATION=1 and must not require runtime-only values such as SITE_URL, DATABASE_URL, S3_*, auth secrets, Stripe keys, or email keys. Those belong to container runtime env.

OAuth variables are not Docker build inputs. OAUTH_GITHUB_CLIENT_ID / OAUTH_GOOGLE_CLIENT_ID are only Web/API auth runtime config when GitHub/Google login is enabled, and they should be injected at container runtime together with the matching *_CLIENT_SECRET. Trigger/AI runtime does not need these two variables.

Trigger dispatch variables are not Docker build inputs either. TRIGGER_SECRET_KEY belongs in Web/API container runtime only, where it selects the Trigger adapter and lets the app enqueue Trigger.dev runs. Do not put it in GHCR build secrets.

Container runtime public config:

Optional Feature Variables

Local .env Example (Better Auth)

PUBLIC_AUTH_PROVIDER=better-auth

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/bunship
BETTER_AUTH_SECRET=replace-with-long-random-secret
AUTH_SECRET=replace-with-long-random-secret

SITE_URL=http://localhost:3001
TRUSTED_ORIGINS=http://localhost:3001,http://localhost:9001

ADMIN_EMAIL_LIST=admin@example.com
EMAIL_FROM=Bunship <noreply@example.com>
RESEND_API_KEY=re_xxx

OAUTH_GITHUB_CLIENT_ID=xxx
OAUTH_GITHUB_CLIENT_SECRET=xxx
OAUTH_GOOGLE_CLIENT_ID=xxx
OAUTH_GOOGLE_CLIENT_SECRET=xxx
PUBLIC_OAUTH_GOOGLE_CLIENT_ID=xxx

S3_ENDPOINT=https://s3.example.com
S3_REGION=auto
S3_ACCESS_KEY=xxx
S3_SECRET_KEY=xxx
S3_BUCKET=bunship
PUBLIC_S3_URL_BASE=https://cdn.example.com

STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
CREEM_API_KEY=creem_xxx
CREEM_WEBHOOK_SECRET=creem_whsec_xxx
PAYMENT_PROVIDER_DEFAULT=stripe
S_GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
CLOUDFLARE_ACCOUNT_ID=xxx

Local .env Example (Clerk)

PUBLIC_AUTH_PROVIDER=clerk

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/bunship

SITE_URL=http://localhost:3001
TRUSTED_ORIGINS=http://localhost:3001,http://localhost:9001

PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
CLERK_WEBHOOK_SECRET=whsec_xxx

ADMIN_EMAIL_LIST=admin@example.com
EMAIL_FROM=Bunship <noreply@example.com>
RESEND_API_KEY=re_xxx

S3_ENDPOINT=https://s3.example.com
S3_REGION=auto
S3_ACCESS_KEY=xxx
S3_SECRET_KEY=xxx
S3_BUCKET=bunship
PUBLIC_S3_URL_BASE=https://cdn.example.com

STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
S_GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
CLOUDFLARE_ACCOUNT_ID=xxx