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

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

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"

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.

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"

See Also

• Database Configuration - Set up PostgreSQL
• Email Configuration - Configure email delivery
• Storage Configuration - Set up S3 storage
• Signing Certificate - Configure document signing
• Troubleshooting - Common configuration issues