Environment Variables

Required Variables

These variables must be set for Documenso to function:

Server Configuration

Database Configuration

Documenso requires PostgreSQL 14 or higher.

Connection string format:

postgres://user:password@host:port/database

For detailed database setup, see Database Configuration.

Authentication and Security

Core Authentication

Google OAuth

Callback URL: https://<your-domain>/api/auth/callback/google

Microsoft OAuth

Callback URL: https://<your-domain>/api/auth/callback/microsoft

Generic OIDC

Webhooks

Before delivering a webhook, Documenso checks whether the target resolves to a private or loopback address and blocks it if so. This check is best-effort and fails open. Use NEXT_PRIVATE_WEBHOOK_SSRF_BYPASS_HOSTS to allow specific internal hosts, for example when delivering to a service on your own network:

NEXT_PRIVATE_WEBHOOK_SSRF_BYPASS_HOSTS="hooks.internal.example,10.0.0.5"

Email Configuration

Documenso supports multiple email transports for sending notifications.

Transport Selection

SMTP Authentication (smtp-auth)

SMTP API (smtp-api)

Resend

MailChannels

Sender Configuration

For detailed email setup, see Email Configuration.

Storage Configuration

Documenso can store documents in the database or S3-compatible storage.

S3 Configuration

Required when NEXT_PUBLIC_UPLOAD_TRANSPORT is set to s3:

CloudFront Distribution (Optional)

For detailed storage setup, see Storage Configuration.

Signing Certificate Configuration

Documenso requires a certificate to digitally sign documents.

Transport Selection

Local Signing

Google Cloud HSM

Cloud Signature Consortium (CSC)

Routes signing through a third-party Trust Service Provider for Advanced and Qualified Electronic Signatures (AES/QES). Instance-wide; set NEXT_PRIVATE_SIGNING_TRANSPORT=csc to enable. See CSC (AES / QES) for the full setup walkthrough.

CSC mode requires an active Enterprise Edition license. Without a valid license, the instance will refuse to start in csc mode.

The OAuth callback URL registered with the CSC provider is fixed at ${NEXT_PUBLIC_WEBAPP_URL}/api/csc/oauth/callback — register this exact URL with the TSP.

Derived Public Variables

The following client-visible variable is derived automatically from the private transport at server startup. Do not set it manually — any value set in the environment is overwritten on boot.

The authoring UI uses this flag to gate features that AES/QES envelopes cannot support (parallel signing, assistant role, dictate next signer). Deriving it from the private transport prevents the client-side flag from drifting from the real server-side configuration.

Signature Options

For detailed certificate setup, see Signing Certificate.

Feature Flags

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.

# 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"

Sign-in Restrictions

You can control which methods are available for users to sign in with the following environment variables:

• NEXT_PUBLIC_DISABLE_SIGNIN (master switch): Set to true to block all signin methods (email/password, Google, Microsoft, OIDC). Hides every signin entry point on /signin and rejects email/password signin server-side with a SIGNIN_DISABLED error.
• NEXT_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNIN: Set to true to disable email/password signin only. The email/password form is hidden, the /forgot-password and /reset-password pages redirect to /signin, and the corresponding server endpoints reject requests. SSO signin is unaffected.
• NEXT_PUBLIC_DISABLE_GOOGLE_SIGNIN, NEXT_PUBLIC_DISABLE_MICROSOFT_SIGNIN, NEXT_PUBLIC_DISABLE_OIDC_SIGNIN: Set to true to hide the matching SSO button on the signin page. Useful when an SSO provider is kept configured for account linking but not advertised as a signin entry point.

These flags are opt-in: when none are set, signin behaviour is unchanged from a stock Documenso instance.

# Allow only OIDC signin (e.g. enterprise SSO-only)
NEXT_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNIN="true"
NEXT_PUBLIC_DISABLE_GOOGLE_SIGNIN="true"
NEXT_PUBLIC_DISABLE_MICROSOFT_SIGNIN="true"

# Or disable signin entirely
NEXT_PUBLIC_DISABLE_SIGNIN="true"

OIDC Auto-redirect

When OIDC is the only enabled signin transport on your instance, /signin automatically redirects users straight to the OIDC provider instead of showing the signin form. The page renders a spinner while the redirect happens. No extra configuration is required — disabling every other signin method is enough to trigger it.

• NEXT_PUBLIC_DISABLE_OIDC_AUTO_REDIRECT: Set to true to opt out of the automatic redirect and keep rendering the signin page even when OIDC is the only enabled transport.

The redirect only triggers when OIDC is configured and email/password, Google, and Microsoft signin are all disabled. If any other transport remains enabled, the signin form is shown as normal.

# OIDC-only signin: disabling all other methods auto-redirects to the provider
NEXT_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNIN="true"
NEXT_PUBLIC_DISABLE_GOOGLE_SIGNIN="true"
NEXT_PUBLIC_DISABLE_MICROSOFT_SIGNIN="true"

# Opt out of the auto-redirect while still OIDC-only
# NEXT_PUBLIC_DISABLE_OIDC_AUTO_REDIRECT="true"

AI Features

Documenso can use Google Vertex AI for recipient and field detection.

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 service that converts them to PDF. When NEXT_PRIVATE_DOCUMENT_CONVERSION_URL is unset, DOCX uploads are rejected and only PDFs are accepted.

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.

Background Jobs

Documenso supports multiple background job providers for processing emails, documents, webhooks, and scheduled tasks.

Provider Selection

Local (local)

No additional configuration required. Jobs are stored in PostgreSQL and processed via internal HTTP requests.

BullMQ (bullmq)

Inngest (inngest)

For setup guides and provider recommendations, see Background Jobs.

Telemetry

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

Enterprise Features

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 editor, and 21 CFR Part 11 compliance. See Apply Your License Key for step-by-step setup.

Example .env File

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"

# 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"

# Sign-in restrictions (optional)
# NEXT_PUBLIC_DISABLE_SIGNIN="true"
# NEXT_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNIN="true"
# NEXT_PUBLIC_DISABLE_GOOGLE_SIGNIN="true"
# NEXT_PUBLIC_DISABLE_MICROSOFT_SIGNIN="true"
# NEXT_PUBLIC_DISABLE_OIDC_SIGNIN="true"

# Opt out of the automatic OIDC redirect when OIDC is the only enabled transport (optional)
# NEXT_PUBLIC_DISABLE_OIDC_AUTO_REDIRECT="true"

See Also

• Database Configuration - Set up PostgreSQL
• Email Configuration - Configure email delivery
• Storage Configuration - Set up S3 storage
• Signing Certificate - Configure document signing
• Organisation Limits - Set per-organisation document, email, and API limits from the admin panel
• Troubleshooting - Common configuration issues