Environment
Environment variables and configuration for Parchment.
All configuration is done via environment variables. Copy .env.example to .env and fill in the values.
Database
| Variable | Description | Default |
|---|---|---|
POSTGRES_DB | Database name | — |
POSTGRES_USER | Database user | — |
POSTGRES_PASSWORD | Database password | — |
Server
| Variable | Description | Default |
|---|---|---|
SERVER_ORIGIN | Public URL of the API server | http://localhost:5000 |
CLIENT_ORIGIN | Public URL of the frontend | http://localhost:5173 |
The CLIENT_ORIGIN variable controls which origins the API allows requests from. In production, set it to your exact frontend domain.
Security keys
These two keys must be independent random 32-byte values. Generate them separately:
openssl rand -base64 32 # → SERVER_IDENTITY_PRIVATE_KEY
openssl rand -base64 32 # → PARCHMENT_INTEGRATION_ENCRYPTION_KEY| Variable | Description |
|---|---|
SERVER_IDENTITY_PRIVATE_KEY | Ed25519 seed for federation server identity. Persist across restarts — rotation breaks TOFU pinning on peers. |
PARCHMENT_INTEGRATION_ENCRYPTION_KEY | AES-256 master key for encrypting third-party API keys stored in the integrations table. |
Both are required — the server refuses to start without them.
Email (optional)
Used for sign-in verification codes and user invitations. Email is optional — if not configured, OTP codes are logged to the server console and invitation emails are skipped. See Email Setup for provider-specific instructions.
| Variable | Description | Default |
|---|---|---|
SMTP_HOST | SMTP server hostname | — |
SMTP_PORT | SMTP server port | 465 |
SMTP_SECURE | Use TLS | true |
SMTP_USER | SMTP username | — |
SMTP_PASS | SMTP password or API key | — |
SMTP_FROM | Sender address | Parchment <noreply@parchment.app> |
APP_TESTER_EMAIL | Email used in automated tests | — |
Documentation Site
| Variable | Description | Default |
|---|---|---|
NEXT_PUBLIC_CLIENT_ORIGIN | App URL shown in the docs header | http://localhost:5173 |
Billing (optional)
Billing is powered by Polar and gated by a signed license token. When these variables are not set, all features are unlocked for every user. See Billing & Subscriptions for full setup instructions.
| Variable | Description | Required |
|---|---|---|
PARCHMENT_LICENSE | Signed license token (Ed25519) | Production only |
POLAR_ACCESS_TOKEN | Polar API access token | No |
POLAR_WEBHOOK_SECRET | Polar webhook signing secret | No |
POLAR_ORGANIZATION_ID | Your Polar organization ID | No |
POLAR_PREMIUM_PRODUCT_ID | Polar product ID for the Premium tier | No |
POLAR_SANDBOX | Set to true to use Polar's sandbox environment | No |
REGISTRATION_MODE | invite (default) or open | No |
In development (NODE_ENV=development), the license check is skipped — only the Polar credentials are needed.
Integrations
Third-party integrations can be enabled in the app under Settings → Integrations. Each may require its own API key at the instance level.
Observability
The server supports OpenTelemetry for tracing and log export:
| Variable | Description |
|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP endpoint for traces and logs |
OTEL_SERVICE_NAME | Service name in traces |