Ryan/documenso
1
0
Fork 1
mirror of https://github.com/documenso/documenso.git synced 2026-07-17 00:30:21 +10:00
Code Issues Packages Projects Releases Wiki Activity
Files
ad559f72dd4927f47839589e751e93d06c6f4986
documenso/apps/docs/content/docs/self-hosting/configuration/environment.mdx
T
Lucas Smith ad559f72dd feat: add BullMQ background job provider with Bull Board dashboard (#2657) 
Add a new BullMQ/Redis-backed job provider as an alternative to the
existing Inngest and Local providers. Includes Bull Board UI for job
monitoring at /api/jobs/board (admin-only in production, open in dev).
2026-04-01 13:07:47 +11:00

386 lines
22 KiB
Plaintext
Raw Blame History

---
title: Environment Variables
description: Complete reference for all environment variables used to configure a self-hosted Documenso instance.
---
## Required Variables
These variables must be set for Documenso to function:
| Variable | Description |
| --------------------------------------- | ------------------------------------------------------------------------------------------ |
| `NEXTAUTH_SECRET` | Secret key for NextAuth.js encryption and signing. Generate with `openssl rand -base64 32` |
| `NEXT_PRIVATE_ENCRYPTION_KEY` | Primary encryption key for symmetric encryption (minimum 32 characters) |
| `NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY` | Secondary encryption key for symmetric encryption (minimum 32 characters) |
| `NEXT_PUBLIC_WEBAPP_URL` | Public URL of your Documenso instance (e.g., `https://sign.example.com`) |
| `NEXT_PRIVATE_DATABASE_URL` | PostgreSQL connection URL with connection pooling |
| `NEXT_PRIVATE_SMTP_FROM_ADDRESS` | Email address used as the sender for all outgoing emails |
| `NEXT_PRIVATE_SMTP_FROM_NAME` | Display name for the sender of outgoing emails |
---
## Server Configuration
| Variable | Description | Default |
| ---------------------------------- | ------------------------------------------------------------ | -------------------------------- |
| `PORT` | Port the server listens on | `3000` |
| `NEXT_PRIVATE_INTERNAL_WEBAPP_URL` | Internal URL for the app to request itself (background jobs) | Same as `NEXT_PUBLIC_WEBAPP_URL` |
---
## Database Configuration
Documenso requires PostgreSQL 14 or higher.
| Variable | Required | Description |
| ---------------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
| `NEXT_PRIVATE_DATABASE_URL` | Yes | PostgreSQL connection URL. Supports connection pooling (e.g., PgBouncer) |
| `NEXT_PRIVATE_DIRECT_DATABASE_URL` | When pooling | Direct PostgreSQL URL for migrations. Defaults to `NEXT_PRIVATE_DATABASE_URL` when not set |
**Connection string format:**
```
postgres://user:password@host:port/database
```
For detailed database setup, see [Database Configuration](/docs/self-hosting/configuration/database).
---
## Authentication and Security
### Core Authentication
| Variable | Required | Description |
| --------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `NEXTAUTH_SECRET` | Yes | Secret for NextAuth.js session encryption. Must be at least 32 characters |
| `NEXT_PRIVATE_ENCRYPTION_KEY` | Yes | Primary key for encrypting sensitive data. Must be at least 32 characters |
| `NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY` | Yes | Secondary encryption key for key rotation. Must be at least 32 characters |
### Google OAuth
| Variable | Required | Description |
| ----------------------------------- | -------- | -------------------------- |
| `NEXT_PRIVATE_GOOGLE_CLIENT_ID` | No | Google OAuth client ID |
| `NEXT_PRIVATE_GOOGLE_CLIENT_SECRET` | No | Google OAuth client secret |
Callback URL: `https://<your-domain>/api/auth/callback/google`
### Microsoft OAuth
| Variable | Required | Description |
| -------------------------------------- | -------- | ---------------------------------------- |
| `NEXT_PRIVATE_MICROSOFT_CLIENT_ID` | No | Microsoft/Azure AD application client ID |
| `NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET` | No | Microsoft/Azure AD client secret |
Callback URL: `https://<your-domain>/api/auth/callback/microsoft`
### Generic OIDC
| Variable | Default | Description |
| ---------------------------------- | ------- | -------------------------------------------------- |
| `NEXT_PRIVATE_OIDC_WELL_KNOWN` | - | OIDC provider well-known configuration URL |
| `NEXT_PRIVATE_OIDC_CLIENT_ID` | - | OIDC client ID |
| `NEXT_PRIVATE_OIDC_CLIENT_SECRET` | - | OIDC client secret |
| `NEXT_PRIVATE_OIDC_PROVIDER_LABEL` | `OIDC` | Label displayed on the OIDC sign-in button |
| `NEXT_PRIVATE_OIDC_SKIP_VERIFY` | `false` | Skip email verification for OIDC accounts |
| `NEXT_PRIVATE_OIDC_PROMPT` | `login` | OIDC prompt parameter. Set to empty string to omit |
---
## Email Configuration
Documenso supports multiple email transports for sending notifications.
### Transport Selection
| Variable | Description | Default |
| ----------------------------- | --------------------------------------------------------------------- | ----------- |
| `NEXT_PRIVATE_SMTP_TRANSPORT` | Email transport: `smtp-auth`, `smtp-api`, `resend`, or `mailchannels` | `smtp-auth` |
### SMTP Authentication (smtp-auth)
| Variable | Default | Description |
| ------------------------------------- | ----------- | ---------------------------------------- |
| `NEXT_PRIVATE_SMTP_HOST` | `127.0.0.1` | SMTP server hostname |
| `NEXT_PRIVATE_SMTP_PORT` | `587` | SMTP server port |
| `NEXT_PRIVATE_SMTP_USERNAME` | - | SMTP authentication username |
| `NEXT_PRIVATE_SMTP_PASSWORD` | - | SMTP authentication password |
| `NEXT_PRIVATE_SMTP_SECURE` | `false` | Force TLS connection (`true` or `false`) |
| `NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS` | `false` | Disable TLS entirely (not recommended) |
| `NEXT_PRIVATE_SMTP_SERVICE` | - | Nodemailer service name (e.g., `gmail`) |
### SMTP API (smtp-api)
| Variable | Default | Description |
| ------------------------------- | -------- | ------------------------------------ |
| `NEXT_PRIVATE_SMTP_HOST` | - | SMTP server hostname |
| `NEXT_PRIVATE_SMTP_PORT` | `587` | SMTP server port |
| `NEXT_PRIVATE_SMTP_APIKEY_USER` | `apikey` | API key user for SMTP authentication |
| `NEXT_PRIVATE_SMTP_APIKEY` | - | API key for SMTP authentication |
### Resend
| Variable | Description |
| ----------------------------- | ----------------------- |
| `NEXT_PRIVATE_RESEND_API_KEY` | API key from Resend.com |
### MailChannels
| Variable | Description | Default |
| -------------------------------------------- | --------------------------------- | ----------------------------------------- |
| `NEXT_PRIVATE_MAILCHANNELS_API_KEY` | MailChannels API key | - |
| `NEXT_PRIVATE_MAILCHANNELS_ENDPOINT` | Custom API endpoint (for proxies) | `https://api.mailchannels.net/tx/v1/send` |
| `NEXT_PRIVATE_MAILCHANNELS_DKIM_DOMAIN` | Domain for DKIM signing | - |
| `NEXT_PRIVATE_MAILCHANNELS_DKIM_SELECTOR` | DKIM selector | - |
| `NEXT_PRIVATE_MAILCHANNELS_DKIM_PRIVATE_KEY` | DKIM private key | - |
### Sender Configuration
| Variable | Description |
| -------------------------------- | ------------------------------- |
| `NEXT_PRIVATE_SMTP_FROM_ADDRESS` | Sender email address (required) |
| `NEXT_PRIVATE_SMTP_FROM_NAME` | Sender display name (required) |
For detailed email setup, see [Email Configuration](/docs/self-hosting/configuration/email).
---
## Storage Configuration
Documenso can store documents in the database or S3-compatible storage.
| Variable | Description | Default |
| ---------------------------------------- | ------------------------------------------- | ---------- |
| `NEXT_PUBLIC_UPLOAD_TRANSPORT` | Storage backend: `database` or `s3` | `database` |
| `NEXT_PUBLIC_DOCUMENT_SIZE_UPLOAD_LIMIT` | Maximum upload size displayed to users (MB) | `5` |
### S3 Configuration
Required when `NEXT_PUBLIC_UPLOAD_TRANSPORT` is set to `s3`:
| Variable | Description | Default |
| --------------------------------------- | ---------------------------------------------- | ----------- |
| `NEXT_PRIVATE_UPLOAD_BUCKET` | S3 bucket name | |
| `NEXT_PRIVATE_UPLOAD_REGION` | S3 region | `us-east-1` |
| `NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID` | S3 access key ID | |
| `NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY` | S3 secret access key | |
| `NEXT_PRIVATE_UPLOAD_ENDPOINT` | Custom S3 endpoint for S3-compatible providers | |
| `NEXT_PRIVATE_UPLOAD_FORCE_PATH_STYLE` | Use path-style URLs instead of virtual hosts | `false` |
### CloudFront Distribution (Optional)
| Variable | Description |
| ----------------------------------------------- | ------------------------------- |
| `NEXT_PRIVATE_UPLOAD_DISTRIBUTION_DOMAIN` | CloudFront distribution domain |
| `NEXT_PRIVATE_UPLOAD_DISTRIBUTION_KEY_ID` | CloudFront key pair ID |
| `NEXT_PRIVATE_UPLOAD_DISTRIBUTION_KEY_CONTENTS` | CloudFront private key contents |
For detailed storage setup, see [Storage Configuration](/docs/self-hosting/configuration/storage).
---
## Signing Certificate Configuration
Documenso requires a certificate to digitally sign documents.
### Transport Selection
| Variable | Description | Default |
| -------------------------------- | ---------------------------------------- | ------- |
| `NEXT_PRIVATE_SIGNING_TRANSPORT` | Signing backend: `local` or `gcloud-hsm` | `local` |
### Local Signing
| Variable | Description |
| ------------------------------------------ | -------------------------------------------------------------- |
| `NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH` | Path to the `.p12` certificate file |
| `NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` | Base64-encoded `.p12` file contents (alternative to file path) |
| `NEXT_PRIVATE_SIGNING_PASSPHRASE` | Passphrase for the certificate |
### Google Cloud HSM
| Variable | Description |
| -------------------------------------------------------------- | ---------------------------------------------------- |
| `NEXT_PRIVATE_SIGNING_GCLOUD_HSM_KEY_PATH` | Google Cloud HSM key path |
| `NEXT_PRIVATE_SIGNING_GCLOUD_HSM_PUBLIC_CRT_FILE_PATH` | Path to the public certificate file |
| `NEXT_PRIVATE_SIGNING_GCLOUD_HSM_PUBLIC_CRT_FILE_CONTENTS` | Base64-encoded public certificate |
| `NEXT_PRIVATE_SIGNING_GCLOUD_APPLICATION_CREDENTIALS_CONTENTS` | Base64-encoded Google Cloud credentials |
| `NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_FILE_PATH` | Path to the certificate chain file |
| `NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_CONTENTS` | Base64-encoded certificate chain |
| `NEXT_PRIVATE_SIGNING_GCLOUD_HSM_SECRET_MANAGER_CERT_PATH` | Google Secret Manager path for certificate retrieval |
### Signature Options
| Variable | Description | Default |
| ------------------------------------------- | ----------------------------------------------------------- | ---------- |
| `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` | Comma-separated timestamp authority URLs for LTV signatures | |
| `NEXT_PUBLIC_SIGNING_CONTACT_INFO` | Contact info embedded in PDF signatures | Webapp URL |
| `NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER` | Use `adbe.pkcs7.detached` instead of `ETSI.CAdES.detached` | `false` |
For detailed certificate setup, see [Signing Certificate](/docs/self-hosting/configuration/signing-certificate).
---
## Feature Flags
| Variable | Description | Default |
| ------------------------------------- | ----------------------------------------------------------------------------------- | ------- |
| `NEXT_PUBLIC_DISABLE_SIGNUP` | Disable public user registration entirely | `false` |
| `NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS` | Comma-separated list of email domains allowed to sign up (e.g., `example.com,acme.org`) | |
| `NEXT_PUBLIC_POSTHOG_KEY` | PostHog API key for analytics and feature flags | |
| `NEXT_PUBLIC_FEATURE_BILLING_ENABLED` | Enable billing features | `false` |
### Signup Restrictions
You can control who is allowed to create accounts on your instance using two environment variables:
- **`NEXT_PUBLIC_DISABLE_SIGNUP`**: Set to `true` to block all new signups. Existing users can still sign in. This applies to both email/password and OAuth signups.
- **`NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS`**: Restrict signups to specific email domains. When set, only users whose email address matches one of the listed domains can create an account. Leave empty to allow all domains.
Both restrictions apply to email/password registration and OAuth (Google, Microsoft, OIDC). If a user attempts to sign up via OAuth with a disallowed domain, they are redirected to the sign-in page with an error.
When both variables are set, `NEXT_PUBLIC_DISABLE_SIGNUP` takes precedence. Signups are blocked regardless of the domain list.
```bash
# Allow signups only from specific domains
NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS="example.com,acme.org"
# Or disable signups entirely
NEXT_PUBLIC_DISABLE_SIGNUP="true"
```
---
## AI Features
Documenso can use Google Vertex AI for recipient and field detection.
| Variable | Description | Default |
| -------------------------- | ---------------------------------------------- | -------- |
| `GOOGLE_VERTEX_PROJECT_ID` | Google Cloud project ID with Vertex AI enabled | |
| `GOOGLE_VERTEX_API_KEY` | Vertex AI Express API key | |
| `GOOGLE_VERTEX_LOCATION` | Vertex AI region | `global` |
AI features must also be enabled in organisation/team settings after configuration.
---
## Background Jobs
Documenso supports multiple background job providers for processing emails, documents, webhooks, and scheduled tasks.
### Provider Selection
| Variable | Description | Default |
| ---------------------------- | -------------------------------------------------------------------------------------- | ------- |
| `NEXT_PRIVATE_JOBS_PROVIDER` | Jobs provider: `local` (PostgreSQL), `bullmq` (Redis), or `inngest` (managed service) | `local` |
### Local (local)
No additional configuration required. Jobs are stored in PostgreSQL and processed via internal HTTP requests.
| Variable | Description | Default |
| ---------------------------------- | ------------------------------------------------------------ | -------------------------------- |
| `NEXT_PRIVATE_INTERNAL_WEBAPP_URL` | Internal URL for the app to send job requests to itself | Same as `NEXT_PUBLIC_WEBAPP_URL` |
### BullMQ (bullmq)
| Variable | Required | Description | Default |
| ---------------------------------- | -------- | ------------------------------------------------------------- | ----------- |
| `NEXT_PRIVATE_REDIS_URL` | Yes | Redis connection URL (e.g., `redis://localhost:6379`) | |
| `NEXT_PRIVATE_REDIS_PREFIX` | No | Key prefix for Redis queues (useful when sharing an instance) | `documenso` |
| `NEXT_PRIVATE_BULLMQ_CONCURRENCY` | No | Number of concurrent jobs to process | `10` |
### Inngest (inngest)
| Variable | Required | Description |
| -------------------------------- | -------- | -------------------------------------------- |
| `NEXT_PRIVATE_INNGEST_EVENT_KEY` | Yes | Inngest event key |
| `INNGEST_EVENT_KEY` | No | Alternative Inngest event key |
| `INNGEST_SIGNING_KEY` | Yes | Inngest signing key for webhook verification |
| `NEXT_PRIVATE_INNGEST_APP_ID` | No | Custom Inngest app ID |
For setup guides and provider recommendations, see [Background Jobs](/docs/self-hosting/configuration/background-jobs).
---
## Telemetry
| Variable | Description | Default |
| ----------------------------- | -------------------------------------------- | ------- |
| `DOCUMENSO_DISABLE_TELEMETRY` | Set to `true` to disable anonymous telemetry | `false` |
Telemetry also auto-disables when `NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY` is configured.
Telemetry collects only: app version, installation ID, and node ID. No personal data is collected.
---
## Debugging and Logging
| Variable | Description |
| ------------------------------------------ | -------------------------------------------------- |
| `NEXT_PRIVATE_LOGGER_FILE_PATH` | File path for log output. Disables stdout when set |
| `NEXT_PRIVATE_BROWSERLESS_URL` | Browserless.io URL for PDF generation |
| `NEXT_PUBLIC_USE_INTERNAL_URL_BROWSERLESS` | Use internal webapp URL in browserless requests |
---
## Enterprise Features
These variables require an active [Enterprise Edition](/docs/policies/enterprise-edition) license. Obtain a license key from [license.documenso.com](https://license.documenso.com) and set it below to unlock enterprise features such as SSO, embed authoring, and 21 CFR Part 11 compliance.
| Variable | Description |
| ------------------------------------ | ------------------------------------------------ |
| `NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY` | License key for enterprise features |
| `NEXT_PRIVATE_STRIPE_API_KEY` | Stripe API key for billing |
| `NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET` | Stripe webhook secret |
| `NEXT_PRIVATE_SES_ACCESS_KEY_ID` | AWS SES access key for email domain verification |
| `NEXT_PRIVATE_SES_SECRET_ACCESS_KEY` | AWS SES secret key |
| `NEXT_PRIVATE_SES_REGION` | AWS SES region |
---
## Example .env File
A minimal production configuration:
```bash
# Required
NEXTAUTH_SECRET="your-random-secret-at-least-32-chars"
NEXT_PRIVATE_ENCRYPTION_KEY="your-encryption-key-at-least-32-chars"
NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY="your-secondary-key-at-least-32-chars"
NEXT_PUBLIC_WEBAPP_URL="https://sign.example.com"
# Database
NEXT_PRIVATE_DATABASE_URL="postgres://user:password@localhost:5432/documenso"
NEXT_PRIVATE_DIRECT_DATABASE_URL="postgres://user:password@localhost:5432/documenso"
# Email
NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="smtp.example.com"
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME="your-smtp-user"
NEXT_PRIVATE_SMTP_PASSWORD="your-smtp-password"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="noreply@example.com"
# Signing (certificate must be configured)
NEXT_PRIVATE_SIGNING_PASSPHRASE="your-certificate-password"
# Signup restrictions (optional)
# NEXT_PUBLIC_DISABLE_SIGNUP="true"
# NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS="example.com,acme.org"
```
---
## See Also
- [Database Configuration](/docs/self-hosting/configuration/database) - Set up PostgreSQL
- [Email Configuration](/docs/self-hosting/configuration/email) - Configure email delivery
- [Storage Configuration](/docs/self-hosting/configuration/storage) - Set up S3 storage
- [Signing Certificate](/docs/self-hosting/configuration/signing-certificate) - Configure document signing
- [Troubleshooting](/docs/self-hosting/maintenance/troubleshooting) - Common configuration issues
Reference in New Issue View Git Blame Copy Permalink