Environment Variables Reference

Complete reference of all environment variables for configuring your self-hosted Documenso instance

This page provides a comprehensive reference of all environment variables available for configuring your self-hosted Documenso instance.

Core Configuration

Authentication

NEXTAUTH_SECRET · string · required

Secret key used by NextAuth.js for session encryption. Must be a random string.

NEXTAUTH_SECRET="your-random-secret-here"

Encryption

NEXT_PRIVATE_ENCRYPTION_KEY · string · required

Application key for symmetric encryption and decryption. Must be a random string of at least 32 characters.

NEXT_PRIVATE_ENCRYPTION_KEY="your-32-character-encryption-key"

NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY · string · required

Secondary encryption key for key rotation. Must be a random string of at least 32 characters.

NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY="your-32-character-secondary-key"

Keep your encryption keys secure and never commit them to version control. These keys protect sensitive document data.

URLs

NEXT_PUBLIC_WEBAPP_URL · string · required

The public URL where your Documenso instance is accessible.

NEXT_PUBLIC_WEBAPP_URL="https://documenso.example.com"

NEXT_PRIVATE_INTERNAL_WEBAPP_URL · string · default: "http://localhost:3000"

URL used by the web app to request itself (e.g., for local background jobs). Useful in containerized environments.

NEXT_PRIVATE_INTERNAL_WEBAPP_URL="http://localhost:3000"

Server

PORT · number · default: "3000"

The port the server will listen on.

PORT=3000

Database Configuration

NEXT_PRIVATE_DATABASE_URL · string · required

PostgreSQL connection string for the database. Used for connection pooling.

NEXT_PRIVATE_DATABASE_URL="postgres://user:password@localhost:5432/documenso"

NEXT_PRIVATE_DIRECT_DATABASE_URL · string · required

Direct PostgreSQL connection string for migrations and operations that don’t work with connection pools.

NEXT_PRIVATE_DIRECT_DATABASE_URL="postgres://user:password@localhost:5432/documenso"

When using services like Supabase or connection poolers (PgBouncer), you’ll need separate URLs for pooled and direct connections.

OAuth Providers (Optional)

Google OAuth

NEXT_PRIVATE_GOOGLE_CLIENT_ID · string

Google OAuth client ID. See Setting up OAuth providers.

NEXT_PRIVATE_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"

NEXT_PRIVATE_GOOGLE_CLIENT_SECRET · string

Google OAuth client secret.

NEXT_PRIVATE_GOOGLE_CLIENT_SECRET="your-client-secret"

Microsoft OAuth

NEXT_PRIVATE_MICROSOFT_CLIENT_ID · string

Microsoft OAuth (Azure AD) client ID. See Setting up OAuth providers.

NEXT_PRIVATE_MICROSOFT_CLIENT_ID="your-client-id"

NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET · string

Microsoft OAuth client secret.

NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET="your-client-secret"

Generic OIDC Provider

NEXT_PRIVATE_OIDC_WELL_KNOWN · string

OpenID Connect discovery endpoint URL.

NEXT_PRIVATE_OIDC_WELL_KNOWN="https://auth.example.com/.well-known/openid-configuration"

NEXT_PRIVATE_OIDC_CLIENT_ID · string

OIDC client ID.

NEXT_PRIVATE_OIDC_CLIENT_SECRET · string

OIDC client secret.

NEXT_PRIVATE_OIDC_PROVIDER_LABEL · string · default: "OIDC"

Display label for the OIDC provider on the login page.

NEXT_PRIVATE_OIDC_SKIP_VERIFY · string

Set to "true" to skip SSL certificate verification (not recommended for production).

NEXT_PRIVATE_OIDC_PROMPT · string · default: "login"

Specifies the prompt parameter for OIDC signin. Set to empty string to omit the prompt parameter.

See: OpenID Connect OAuth2 Prompts

Document Signing Configuration

See the Signing Certificate section for detailed configuration.

NEXT_PRIVATE_SIGNING_TRANSPORT · string · default: "local"

The transport to use for document signing.

Options:

• local - File-based signing with .p12 certificate (default)
• gcloud-hsm - Google Cloud KMS signing

NEXT_PRIVATE_SIGNING_TRANSPORT="local"

NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY · string

Comma-separated list of timestamp authority URLs for PDF signing. Enables Long-Term Validation (LTV) and archival timestamps.

NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY="http://timestamp.digicert.com,http://timestamp.globalsign.com/tsa/r6advanced1"

NEXT_PUBLIC_SIGNING_CONTACT_INFO · string

Contact info to embed in PDF signatures. Defaults to the webapp URL.

NEXT_PUBLIC_SIGNING_CONTACT_INFO="[e-mail]"

NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER · string

Set to "true" to use the legacy adbe.pkcs7.detached subfilter instead of ETSI.CAdES.detached.

NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER="false"

Storage Configuration

See Storage Configuration for detailed setup.

NEXT_PUBLIC_UPLOAD_TRANSPORT · string · default: "database"

Defines the storage transport to use.

Options:

• database - Store files in PostgreSQL (default, suitable for small deployments)
• s3 - Store files in S3 or S3-compatible storage

NEXT_PUBLIC_UPLOAD_TRANSPORT="s3"

Email Configuration

See Email Configuration for detailed setup.

NEXT_PRIVATE_SMTP_TRANSPORT · string · default: "smtp-auth"

Defines the transport to use for sending emails.

Options:

• smtp-auth - Standard SMTP with authentication (default)
• smtp-api - SMTP with API key authentication (e.g., SendGrid)
• resend - Resend.com API
• mailchannels - MailChannels API (Cloudflare Workers)

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"

NEXT_PRIVATE_SMTP_FROM_NAME · string · required

Sender name to use for the from address.

NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"

NEXT_PRIVATE_SMTP_FROM_ADDRESS · string · required

Email address to use as the from address.

NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Background Jobs

See Background Jobs Configuration for details.

NEXT_PRIVATE_JOBS_PROVIDER · string · default: "local"

The background job provider to use.

Options:

• local - Built-in job system using PostgreSQL (default, recommended for most deployments)
• inngest - Inngest.com for enterprise deployments

NEXT_PRIVATE_JOBS_PROVIDER="local"

Feature Flags

NEXT_PUBLIC_DOCUMENT_SIZE_UPLOAD_LIMIT · number · default: "5"

Maximum document upload size in megabytes displayed to users.

NEXT_PUBLIC_DOCUMENT_SIZE_UPLOAD_LIMIT=5

NEXT_PUBLIC_FEATURE_BILLING_ENABLED · string

Set to enable billing features (requires Stripe configuration).

NEXT_PUBLIC_FEATURE_BILLING_ENABLED="true"

NEXT_PUBLIC_DISABLE_SIGNUP · string

Set to "true" to disable user signups through the /signup page.

NEXT_PUBLIC_DISABLE_SIGNUP="true"

NEXT_PUBLIC_USE_INTERNAL_URL_BROWSERLESS · boolean · default: "false"

Set to true to use internal webapp URL in browserless requests.

NEXT_PUBLIC_USE_INTERNAL_URL_BROWSERLESS=false

Enterprise Features

NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY · string

License key to enable enterprise features for self-hosted instances.

NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY="your-license-key"

NEXT_PRIVATE_SES_ACCESS_KEY_ID · string

AWS SES access key ID for email domain verification (Enterprise only).

NEXT_PRIVATE_SES_SECRET_ACCESS_KEY · string

AWS SES secret access key for email domain verification (Enterprise only).

NEXT_PRIVATE_SES_REGION · string

AWS SES region for email domain verification (Enterprise only).

Payment Processing (Stripe)

NEXT_PRIVATE_STRIPE_API_KEY · string

Stripe API key for payment processing.

NEXT_PRIVATE_STRIPE_API_KEY="sk_live_..."

NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET · string

Stripe webhook secret for verifying webhook events.

NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET="whsec_..."

AI Features (Google Vertex AI)

GOOGLE_VERTEX_PROJECT_ID · string

Google Cloud Project ID for Vertex AI integration.

GOOGLE_VERTEX_PROJECT_ID="your-project-id"

GOOGLE_VERTEX_LOCATION · string · default: "global"

Google Cloud region for Vertex AI.

GOOGLE_VERTEX_LOCATION="us-central1"

GOOGLE_VERTEX_API_KEY · string

API key for Google Vertex AI (Gemini). Get your key from the Vertex AI Studio Settings.

GOOGLE_VERTEX_API_KEY="your-api-key"

Analytics and Telemetry

NEXT_PUBLIC_POSTHOG_KEY · string

PostHog API key for analytics and feature flags. Leave blank to disable.

NEXT_PUBLIC_POSTHOG_KEY="phc_..."

DOCUMENSO_DISABLE_TELEMETRY · string

Set to "true" to disable anonymous telemetry for self-hosted instances.

Telemetry helps us understand how Documenso is being used and improve the product. We only collect: app version, installation ID, and node ID. No personal data is collected.

DOCUMENSO_DISABLE_TELEMETRY="true"

Support Integration

NEXT_PRIVATE_PLAIN_API_KEY · string

API key for Plain.com support integration.

NEXT_PRIVATE_PLAIN_API_KEY="your-api-key"

Logging

NEXT_PRIVATE_LOGGER_FILE_PATH · string

File path to save logger output. If provided, stdout logging will be disabled.

NEXT_PRIVATE_LOGGER_FILE_PATH="/var/log/documenso/app.log"

Testing and Development

The following environment variables should NEVER be used in production environments.

DANGEROUS_BYPASS_RATE_LIMITS · string

Set to "true" to disable all rate limiting. Only use for E2E tests.

DANGEROUS_BYPASS_RATE_LIMITS="true"

E2E_TEST_AUTHENTICATE_USERNAME · string

Username for E2E test authentication.

E2E_TEST_AUTHENTICATE_USER_EMAIL · string

Email for E2E test authentication.

E2E_TEST_AUTHENTICATE_USER_PASSWORD · string

Password for E2E test authentication.

Next Steps

Signing Configuration

Configure PDF signing certificates

Storage Setup

Set up S3 or database storage

Email Configuration

Configure email delivery

Background Jobs

Set up background job processing