Environment Variables Complete reference for all environment variables used to configure a self-hosted Documenso instance.
These variables must be set for Documenso to function:
Variable Description NEXTAUTH_SECRETSecret key for NextAuth.js encryption and signing. Generate with openssl rand -base64 32 NEXT_PRIVATE_ENCRYPTION_KEYPrimary encryption key for symmetric encryption (minimum 32 characters) NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEYSecondary encryption key for symmetric encryption (minimum 32 characters) NEXT_PUBLIC_WEBAPP_URLPublic URL of your Documenso instance (e.g., https://sign.example.com) NEXT_PRIVATE_DATABASE_URLPostgreSQL connection URL with connection pooling NEXT_PRIVATE_SMTP_FROM_ADDRESSEmail address used as the sender for all outgoing emails NEXT_PRIVATE_SMTP_FROM_NAMEDisplay name for the sender of outgoing emails
Variable Description Default PORTPort the server listens on 3000NEXT_PRIVATE_INTERNAL_WEBAPP_URLInternal URL for the app to request itself (background jobs) Same as NEXT_PUBLIC_WEBAPP_URL
Documenso requires PostgreSQL 14 or higher.
Variable Required Description NEXT_PRIVATE_DATABASE_URLYes PostgreSQL connection URL. Supports connection pooling (e.g., PgBouncer) NEXT_PRIVATE_DIRECT_DATABASE_URLWhen 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 .
Variable Required Description NEXTAUTH_SECRETYes Secret for NextAuth.js session encryption. Must be at least 32 characters NEXT_PRIVATE_ENCRYPTION_KEYYes Primary key for encrypting sensitive data. Must be at least 32 characters NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEYYes Secondary encryption key for key rotation. Must be at least 32 characters
Variable Required Description NEXT_PRIVATE_GOOGLE_CLIENT_IDNo Google OAuth client ID NEXT_PRIVATE_GOOGLE_CLIENT_SECRETNo Google OAuth client secret
Callback URL: https://<your-domain>/api/auth/callback/google
Variable Required Description NEXT_PRIVATE_MICROSOFT_CLIENT_IDNo Microsoft/Azure AD application client ID NEXT_PRIVATE_MICROSOFT_CLIENT_SECRETNo Microsoft/Azure AD client secret
Callback URL: https://<your-domain>/api/auth/callback/microsoft
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_LABELOIDCLabel displayed on the OIDC sign-in button NEXT_PRIVATE_OIDC_SKIP_VERIFYfalseSkip email verification for OIDC accounts NEXT_PRIVATE_OIDC_PROMPTloginOIDC prompt parameter. Set to empty string to omit
Documenso supports multiple email transports for sending notifications.
Variable Description Default NEXT_PRIVATE_SMTP_TRANSPORTEmail transport: smtp-auth, smtp-api, resend, or mailchannels smtp-auth
Variable Default Description NEXT_PRIVATE_SMTP_HOST127.0.0.1SMTP server hostname NEXT_PRIVATE_SMTP_PORT587SMTP server port NEXT_PRIVATE_SMTP_USERNAME- SMTP authentication username NEXT_PRIVATE_SMTP_PASSWORD- SMTP authentication password NEXT_PRIVATE_SMTP_SECUREfalseForce TLS connection (true or false) NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLSfalseDisable TLS entirely (not recommended) NEXT_PRIVATE_SMTP_SERVICE- Nodemailer service name (e.g., gmail)
Variable Default Description NEXT_PRIVATE_SMTP_HOST- SMTP server hostname NEXT_PRIVATE_SMTP_PORT587SMTP server port NEXT_PRIVATE_SMTP_APIKEY_USERapikeyAPI key user for SMTP authentication NEXT_PRIVATE_SMTP_APIKEY- API key for SMTP authentication
Variable Description NEXT_PRIVATE_RESEND_API_KEYAPI key from Resend.com
Variable Description Default NEXT_PRIVATE_MAILCHANNELS_API_KEYMailChannels API key - NEXT_PRIVATE_MAILCHANNELS_ENDPOINTCustom API endpoint (for proxies) https://api.mailchannels.net/tx/v1/sendNEXT_PRIVATE_MAILCHANNELS_DKIM_DOMAINDomain for DKIM signing - NEXT_PRIVATE_MAILCHANNELS_DKIM_SELECTORDKIM selector - NEXT_PRIVATE_MAILCHANNELS_DKIM_PRIVATE_KEYDKIM private key -
Variable Description NEXT_PRIVATE_SMTP_FROM_ADDRESSSender email address (required) NEXT_PRIVATE_SMTP_FROM_NAMESender display name (required)
For detailed email setup, see Email Configuration .
Documenso can store documents in the database or S3-compatible storage.
Variable Description Default NEXT_PUBLIC_UPLOAD_TRANSPORTStorage backend: database or s3 databaseNEXT_PUBLIC_DOCUMENT_SIZE_UPLOAD_LIMITMaximum upload size displayed to users (MB) 5
Required when NEXT_PUBLIC_UPLOAD_TRANSPORT is set to s3:
Variable Description Default NEXT_PRIVATE_UPLOAD_BUCKETS3 bucket name NEXT_PRIVATE_UPLOAD_REGIONS3 region us-east-1NEXT_PRIVATE_UPLOAD_ACCESS_KEY_IDS3 access key ID NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEYS3 secret access key NEXT_PRIVATE_UPLOAD_ENDPOINTCustom S3 endpoint for S3-compatible providers NEXT_PRIVATE_UPLOAD_FORCE_PATH_STYLEUse path-style URLs instead of virtual hosts false
Variable Description NEXT_PRIVATE_UPLOAD_DISTRIBUTION_DOMAINCloudFront distribution domain NEXT_PRIVATE_UPLOAD_DISTRIBUTION_KEY_IDCloudFront key pair ID NEXT_PRIVATE_UPLOAD_DISTRIBUTION_KEY_CONTENTSCloudFront private key contents
For detailed storage setup, see Storage Configuration .
Documenso requires a certificate to digitally sign documents.
Variable Description Default NEXT_PRIVATE_SIGNING_TRANSPORTSigning backend: local or gcloud-hsm local
Variable Description NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATHPath to the .p12 certificate file NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTSBase64-encoded .p12 file contents (alternative to file path) NEXT_PRIVATE_SIGNING_PASSPHRASEPassphrase for the certificate
Variable Description NEXT_PRIVATE_SIGNING_GCLOUD_HSM_KEY_PATHGoogle Cloud HSM key path NEXT_PRIVATE_SIGNING_GCLOUD_HSM_PUBLIC_CRT_FILE_PATHPath to the public certificate file NEXT_PRIVATE_SIGNING_GCLOUD_HSM_PUBLIC_CRT_FILE_CONTENTSBase64-encoded public certificate NEXT_PRIVATE_SIGNING_GCLOUD_APPLICATION_CREDENTIALS_CONTENTSBase64-encoded Google Cloud credentials NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_FILE_PATHPath to the certificate chain file NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_CONTENTSBase64-encoded certificate chain NEXT_PRIVATE_SIGNING_GCLOUD_HSM_SECRET_MANAGER_CERT_PATHGoogle Secret Manager path for certificate retrieval
Variable Description Default NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITYComma-separated timestamp authority URLs for LTV signatures NEXT_PUBLIC_SIGNING_CONTACT_INFOContact info embedded in PDF signatures Webapp URL NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTERUse adbe.pkcs7.detached instead of ETSI.CAdES.detached false
For detailed certificate setup, see Signing Certificate .
Variable Description Default NEXT_PUBLIC_DISABLE_SIGNUPDisable public user registration falseNEXT_PUBLIC_POSTHOG_KEYPostHog API key for analytics and feature flags NEXT_PUBLIC_FEATURE_BILLING_ENABLEDEnable billing features false
Documenso can use Google Vertex AI for recipient and field detection.
Variable Description Default GOOGLE_VERTEX_PROJECT_IDGoogle Cloud project ID with Vertex AI enabled GOOGLE_VERTEX_API_KEYVertex AI Express API key GOOGLE_VERTEX_LOCATIONVertex AI region global
AI features must also be enabled in organisation/team settings after configuration.
Documenso uses a PostgreSQL-based job queue by default. Jobs (email delivery, document processing, webhook dispatch) are stored in the BackgroundJob table and processed via internal HTTP requests. No external queue service like Redis is required.
Variable Description Default NEXT_PRIVATE_JOBS_PROVIDERJobs provider: local (PostgreSQL-based queue) or inngest (managed service) local
Variable Description NEXT_PRIVATE_INNGEST_EVENT_KEYInngest event key INNGEST_EVENT_KEYAlternative Inngest event key INNGEST_SIGNING_KEYInngest signing key for webhook verification NEXT_PRIVATE_INNGEST_APP_IDCustom Inngest app ID
Variable Description Default DOCUMENSO_DISABLE_TELEMETRYSet to true to disable anonymous telemetry false
Telemetry collects only: app version, installation ID, and node ID. No personal data is collected.
Variable Description NEXT_PRIVATE_LOGGER_FILE_PATHFile path for log output. Disables stdout when set NEXT_PRIVATE_BROWSERLESS_URLBrowserless.io URL for PDF generation NEXT_PUBLIC_USE_INTERNAL_URL_BROWSERLESSUse internal webapp URL in browserless requests
These variables require an active Enterprise Edition license. Obtain a license key from 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_KEYLicense key for enterprise features NEXT_PRIVATE_STRIPE_API_KEYStripe API key for billing NEXT_PRIVATE_STRIPE_WEBHOOK_SECRETStripe webhook secret NEXT_PRIVATE_SES_ACCESS_KEY_IDAWS SES access key for email domain verification NEXT_PRIVATE_SES_SECRET_ACCESS_KEYAWS SES secret key NEXT_PRIVATE_SES_REGIONAWS SES region
A minimal production configuration:
# 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"