Configuration

If you run a canvas-drop instance, this is the environment-variable reference: every variable the server reads, its default, and what refuses to boot when it is wrong. Every setting is an environment variable, validated once at startup. One module (packages/shared/src/config/env.ts) is the only reader of process.env; everything else takes typed config. An invalid value or combination fails at boot with a message naming every variable to fix, never at request time. Nothing is reported anywhere: no telemetry, no phone-home.

The defaults below are the schema defaults. .env.example mirrors them with comments; .env.production.example is the annotated production profile.

How config gets loaded

Local dev. pnpm dev reads the root .env file once (node --env-file-if-exists=.env). Copy the template and start:

cp .env.example .env && pnpm dev
# server on http://localhost:3000, dashboard on http://localhost:5173, signed in as dev@example.com

The defaults give you a logged-in instance: path URLs, sqlite, local storage, dev auth.

Production. The .env file is not read. Set variables in the process environment: a systemd EnvironmentFile, the container environment: block, or a secrets manager. The recommended profile (subdomain URLs, proxy auth verified against a JWKS, Postgres, S3) needs this set; everything else keeps its default:

NODE_ENV=production
CANVAS_DROP_URL_MODE=subdomain
CANVAS_DROP_BASE_URL=https://canvases.example.com
CANVAS_DROP_SESSION_SECRET=<output of: openssl rand -hex 32>

CANVAS_DROP_AUTH_MODE=proxy
CANVAS_DROP_AUTH_PROXY_JWT_JWKS_URL=https://idp.example.com/.well-known/jwks.json
CANVAS_DROP_AUTH_PROXY_JWT_ISSUER=https://idp.example.com
CANVAS_DROP_AUTH_PROXY_JWT_AUDIENCE=canvas-drop
CANVAS_DROP_ALLOWED_EMAIL_DOMAINS=example.com
CANVAS_DROP_ADMIN_EMAILS=admin@example.com

CANVAS_DROP_DB=postgres
CANVAS_DROP_DATABASE_URL=postgres://canvasdrop:<password>@db.internal:5432/canvasdrop

CANVAS_DROP_STORAGE=s3
CANVAS_DROP_S3_BUCKET=canvas-drop
CANVAS_DROP_S3_REGION=us-east-1
CANVAS_DROP_S3_ACCESS_KEY=<access key>
CANVAS_DROP_S3_SECRET_KEY=<secret key>

A misconfigured start prints every problem at once and exits with status 1:

Invalid canvas-drop configuration:
  - CANVAS_DROP_SESSION_SECRET: a session secret of at least 32 characters is required outside dev mode (and always in production)
  - CANVAS_DROP_DATABASE_URL: CANVAS_DROP_DATABASE_URL is required when CANVAS_DROP_DB=postgres

Fix the variables above (see .env.example) and restart.

Docker image. The image presets NODE_ENV=production, CANVAS_DROP_PORT=3000, CANVAS_DROP_SQLITE_PATH=/data/canvasdrop.db, CANVAS_DROP_STORAGE_PATH=/data/storage, and CANVAS_DROP_DASHBOARD_DIST=/app/apps/dashboard/dist, with /data as the volume. Everything else comes from the environment you pass in. See Deploy.

Admin view. Admin → Configuration lists the main settings with their source: Environment, Default, or a DB override. Secrets render as set or unset plus the last four characters. A few settings can be edited there at runtime (a DB override layered over env); the tables below mark them runtime-editable. Everything else is env-only by design: a web panel must not be able to flip the auth mode, the database driver, or the session secret. A handful of env-only knobs are not shown in the panel at all (CANVAS_DROP_MCP, CANVAS_DROP_DASHBOARD_DIST, the screenshot tuning values, the proxy header names, CANVAS_DROP_ORG_*, CANVAS_DROP_S3_FORCE_PATH_STYLE, CANVAS_DROP_DEV_USER_*, and the authoring share policy).

Value formats

An empty value counts as unset and takes the default.

Boot-time checks

These combinations are enforced at startup, in addition to each variable's format:

• CANVAS_DROP_AUTH_MODE=dev with NODE_ENV=production refuses to start.
• CANVAS_DROP_URL_MODE=subdomain needs a non-localhost CANVAS_DROP_BASE_URL (localhost, 127.0.0.1, ::1, and *.localhost are rejected).
• CANVAS_DROP_SESSION_SECRET must be at least 32 characters whenever the auth mode is not dev, and always when NODE_ENV=production.
• CANVAS_DROP_DB=postgres requires CANVAS_DROP_DATABASE_URL.
• CANVAS_DROP_STORAGE=s3 requires CANVAS_DROP_S3_BUCKET, CANVAS_DROP_S3_REGION, CANVAS_DROP_S3_ACCESS_KEY, and CANVAS_DROP_S3_SECRET_KEY.
• Every CANVAS_DROP_TRUSTED_PROXY_IPS entry is validated, in every auth mode.
• proxy auth requires CANVAS_DROP_AUTH_PROXY_JWT_JWKS_URL or a non-empty CANVAS_DROP_TRUSTED_PROXY_IPS; with a JWKS URL, CANVAS_DROP_AUTH_PROXY_JWT_ISSUER and CANVAS_DROP_AUTH_PROXY_JWT_AUDIENCE are required too.
• oidc auth requires CANVAS_DROP_OIDC_ISSUER, CANVAS_DROP_OIDC_CLIENT_ID, and CANVAS_DROP_OIDC_CLIENT_SECRET.
• Any auth mode other than dev requires at least one CANVAS_DROP_ALLOWED_EMAIL_DOMAINS entry.
• path URL mode with proxy or oidc auth requires CANVAS_DROP_ALLOW_MULTI_USER_PATH_MODE=true.

Tenancy adds three more once CANVAS_DROP_ORG_NAME is set; see Tenancy.

The four pluggable interfaces

Each interface is selected by one switch variable. Swapping a driver is a config change, never a code change. Migrations run at boot on whichever database is selected, and a backup taken on one driver restores onto another (see Backups and maintenance).

Email transport (CANVAS_DROP_EMAIL_DRIVER) is a fifth, smaller driver seam; see Email transport.

Core

Admin → Configuration also carries core.instanceName, a DB-only display name (default: the host of CANVAS_DROP_BASE_URL) for custom email templates that still use {{instanceName}}. The seeded templates name the recipient email, the inviter, and the specific canvas, team, or sign-in action instead of instance or org branding.

Design skins

A design skin is an instance-wide visual language: the dashboard, the editor, the signed-out landing page, the docs, and the legal pages all change together. It is a token-only layer over the brand tokens: a skin overrides the accent colour family, the display-type bundle (font, weight, tracking), and the corner-radius scale. No skin forks layout or structure. Error pages keep the default look.

Accent lightness is kept conservative in every skin so the accent foreground clears WCAG AA on the fill in light and dark mode.

Two ways to set it, with the same effect for everyone on the instance:

• Admin console. Admin → Configuration → Design skin. Changing the dropdown previews the skin live in your own session; Save writes the override to the database and applies it to all users at runtime, with no restart. Leaving the page without saving reverts your preview.
• CANVAS_DROP_DESIGN_SKIN. The boot default. A DB override set in the console always wins over this value; Clear in the console removes the override and falls back to it.

The skin is global and admin-only. It is not a per-user preference; light or dark theme is the per-user setting.

Auth

CANVAS_DROP_AUTH_MODE selects how identity is established. Identity always comes from the server-side auth strategy, never from anything the client sends. In every mode the same checks run on every request: the email must pass the domain allowlist (or a sign-in permit), the user must not be blocked, and org membership is derived from the verified email domain. See Security model.

Sign-in permits. Beyond the domain list, an admin can permit specific outside emails to sign in (a contractor, a test account) under Admin → People → Sign-in permits. It is an additive, DB-managed layer: the env domain list is unchanged, and an email passes if its domain is allowed or it is on this list. There is no app-owned password; adding an email sends a sign-in invitation (when access emails are on), and removing an entry revokes that email's access on its next sign-in. In proxy mode this list cannot widen the upstream IAP by itself, and no email is sent: admit a brand-new external email in the proxy first, then add it here. See Sign-in permits and access emails.

dev mode

Auto-logs-in a fixed local user with zero setup; no credential is examined. A session cookie still exists so /auth/logout works. Localhost only; production refuses to boot in this mode.

oidc mode

The app owns login: Authorization Code with PKCE against your provider, then an HttpOnly session cookie (__canvasdrop_session, 14-day rolling expiry, SameSite=Lax, Secure in production, Domain=.{baseHost} in subdomain mode, host-only in path mode). An unauthenticated request is redirected to /auth/login. Use this when no identity-aware proxy fronts the app.

proxy mode

Front the app with an identity-aware proxy that asserts identity on every request. The app issues no session cookie; an unauthenticated request gets 401. Exactly one trust path is active, selected by whether CANVAS_DROP_AUTH_PROXY_JWT_JWKS_URL is set. They do not compose: when the JWKS URL is set, identity headers are never honored, even if they arrive (their arrival is logged as a downgrade probe). Boot fails if neither path is configured.

The proxy must be the only way to reach the app, and it must overwrite the identity headers it forwards. See Auth at the edge.

Tenancy: the org boundary (optional)

Names an org so that guests (people who sign in on a non-org domain: a contractor, a personal address, an admin on another domain) cannot see canvases shared with the Whole org rung. Membership is derived server-side from the user's verified email domain; a member can home a canvas in the org, a guest only ever gets Personal.

Off by default. With no CANVAS_DROP_ORG_NAME the feature is inert: Whole org keeps its legacy "any signed-in user" meaning and the home org is ignored everywhere. Setting the name turns it on, so you can deploy first and migrate later.

At boot the instance materializes the org and its domains idempotently. The configured domain set is authoritative: a domain you remove is pruned at the next boot, and its users drop to guest on their next request. Boot fails on a bad config: a domain mapped to two orgs, more than one org (multi-org is a later phase), or an org with no domains. Migrating an existing instance (homing current canvases, clamping guest-owned Whole org rows) is a one-time cutover with a read-only dry run: pnpm tenancy:plan, then pnpm tenancy:plan --apply. After narrowing CANVAS_DROP_ORG_DOMAINS, pnpm tenancy:reconcile --apply revokes the stale domain-sourced memberships. The runbook is docs/tenancy.md in the repo.

Database

Migrations run at boot on the selected database; there is no separate migrate command.

Storage

Screenshots (optional)

Generates canvas preview thumbnails with headless Chromium. The pipeline is off by default and needs two things: Chromium in the image (build with --build-arg SCREENSHOTS=1) and CANVAS_DROP_SCREENSHOTS=on. The env var only sets availability; an admin still turns capture on under Admin → Configuration (screenshots.enabled, runtime-editable, default off). Effective = available and enabled. Each tuning var is an integer ≥ 1. See Screenshots.

Rate limiting

Per-minute request budgets, applied per class with in-process counters over a fixed 60-second window. Env-only: they are read on the hot path and are shown read-only in Admin → Configuration. Each limit is an integer ≥ 1; boot fails on 0 or a negative value, so use the master switch to disable limiting.

AI (optional)

The AI primitive is off until a provider key is present, from CANVAS_DROP_AI_API_KEY or a runtime override. The key is server-side only and never reaches the browser. An empty or whitespace value counts as unset.

Outbound Connections (optional)

Connections stays inert until an admin creates a profile and grants it to a canvas. The root key is optional on a clean instance and for profiles with no protected headers. Once protected values exist, store the same key with the deployment secrets on every restart and restore. It must be base64 for exactly 32 decoded bytes (openssl rand -base64 32). Missing or malformed key material fails protected-header create/use closed without preventing an otherwise unused instance from booting.

All rows are env-only and shown read-only in Admin → Configuration. Limits are per server process; the supported first-release deployment is one app process.

The Connections SDK reference explains the grant, network, header, and response boundaries.

Authoring (optional)

The authoring capability lets a signed-in viewer create a new canvas from a backend-enabled canvas's page, as themselves. It is higher-privilege than the other primitives, so it is off instance-wide by default and the per-canvas Backend toggle also defaults off; both must be on. The share policy (the last three rows) is env-only.

Email transport

Sends the auth-delegated sign-in and access emails for account, canvas, and team access. It is a driver behind an interface, like the database and storage. Provider secrets are env-only, never DB-overridable, and never logged.

proxy mode sends no email. The mailer is not built in that mode (the IAP owns sign-in), so every sign-in or access email is skipped; grants still happen. The variables below apply to dev and oidc.

A driver that cannot send skips the email rather than failing the grant: smtp needs a host, mailgun needs an API key and a domain, noop never sends, log always "sends" (to the log).

Sign-in permits and access emails

These are DB-managed admin settings with no env var, under Admin → Configuration, layered on top of the mailer above. They govern the auth-delegated add-person flow: personal-team adds, canvas Add person, and admin sign-in permits.

Adding a brand-new person to a team or canvas sends them the sign-in invitation, gated only by the master switch and the mailer; existing team members are not re-notified.

Admin → Configuration also holds the runtime quotas for the KV and files primitives, with no env var: quota.kv.keys.shared (default 10000 shared keys per canvas), quota.kv.keys.user (1000 per-user keys), quota.files.bytes.file (26214400, 25 MB per file), and quota.files.bytes.canvas (1073741824, 1 GB per canvas).

Email templates for each message are admin-editable (subject, HTML, text) under Admin → Configuration → Email templates, with {{variable}} substitution from an allow-list (name, recipientEmail, inviterName, canvasTitle, teamName, link, role, accessLabel, personEmail, reason, plus the legacy instanceName, orgName, orgContext) and a reset to the latest default. Values are HTML-escaped in the HTML body; an unknown variable renders empty.

Logging and error tracking

Structured logs go to stdout via pino: no app-side files, rotation, or shipping. /healthz is excluded from request logging.

Tooling-only variables

A few CANVAS_DROP_* names in the repo are read by scripts and tests, not by the server, and are not part of the config schema:

All examples use placeholder values. Never commit real secrets; set them in your deployment environment (systemd, container env, secrets manager).