--- 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:///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:///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` | Master switch. Disable all signup methods application-wide | `false` | | `NEXT_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNUP` | Disable email/password signup only. SSO signup is unaffected | `false` | | `NEXT_PUBLIC_DISABLE_GOOGLE_SIGNUP` | Block new accounts via Google. Existing Google-linked users can still sign in | `false` | | `NEXT_PUBLIC_DISABLE_MICROSOFT_SIGNUP` | Block new accounts via Microsoft. Existing linked users can still sign in | `false` | | `NEXT_PUBLIC_DISABLE_OIDC_SIGNUP` | Block new accounts via OIDC, including the organisation portal | `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 with the following environment variables: - **`NEXT_PUBLIC_DISABLE_SIGNUP`** (master switch): Set to `true` to block all new signups across every method (email/password, Google, Microsoft, OIDC). When set, this also blocks new-account creation through the organisation OIDC authentication portal. - **`NEXT_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNUP`**: Set to `true` to disable email/password signup only. SSO signup is still allowed. - **`NEXT_PUBLIC_DISABLE_GOOGLE_SIGNUP`**, **`NEXT_PUBLIC_DISABLE_MICROSOFT_SIGNUP`**, **`NEXT_PUBLIC_DISABLE_OIDC_SIGNUP`**: Set to `true` to block brand-new account creation through the matching SSO provider. Existing users with the provider already linked can still sign in, and existing users can still link the provider to their account. `NEXT_PUBLIC_DISABLE_OIDC_SIGNUP` also blocks new-account creation through the organisation authentication portal. - **`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. Sign-in for existing users is never affected, only the creation of brand-new accounts. Both the master switch and the domain allowlist 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 the master switch and the domain allowlist are set, the master switch 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" # Allow OIDC signup only; block email/password, Google, Microsoft NEXT_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNUP="true" NEXT_PUBLIC_DISABLE_GOOGLE_SIGNUP="true" NEXT_PUBLIC_DISABLE_MICROSOFT_SIGNUP="true" # 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. --- ## Document Conversion Documenso can accept `.docx` uploads by sending them to a [Gotenberg](https://gotenberg.dev) service that converts them to PDF. When `NEXT_PRIVATE_DOCUMENT_CONVERSION_URL` is unset, DOCX uploads are rejected and only PDFs are accepted. | Variable | Description | Default | | --------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------- | | `NEXT_PRIVATE_DOCUMENT_CONVERSION_URL` | Base URL of the Gotenberg service (e.g., `http://gotenberg:3000`). Unset disables the feature. | | | `NEXT_PRIVATE_DOCUMENT_CONVERSION_USERNAME` | HTTP Basic auth username. Required when Gotenberg runs with `--api-enable-basic-auth`. | | | `NEXT_PRIVATE_DOCUMENT_CONVERSION_PASSWORD` | HTTP Basic auth password. Set together with the username. | | | `NEXT_PRIVATE_DOCUMENT_CONVERSION_TIMEOUT_MS` | Per-request timeout in milliseconds. Increase for very large documents. | `30000` | The public flag `NEXT_PUBLIC_DOCUMENT_CONVERSION_ENABLED` is derived automatically from `NEXT_PRIVATE_DOCUMENT_CONVERSION_URL` on server start. Do not set it manually. For setup, image-build instructions, and security recommendations, see [Document Conversion](/docs/self-hosting/configuration/advanced/document-conversion). --- ## 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 editor, 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_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNUP="true" # NEXT_PUBLIC_DISABLE_GOOGLE_SIGNUP="true" # NEXT_PUBLIC_DISABLE_MICROSOFT_SIGNUP="true" # NEXT_PUBLIC_DISABLE_OIDC_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