Manual installation gives you full control over the Documenso deployment. This guide walks through building from source and running on your own infrastructure.
Prerequisites
Install Node.js
Documenso requires Node.js v22.0.0 or higher. node --version # Should be v22.0.0+
Download Node.js
Setup SMTP Server
Have SMTP credentials ready for sending emails. You can use:
Gmail SMTP
SendGrid
Postmark
Any other SMTP provider
Installation Steps Step 1: Clone the Repository Clone the Documenso repository from GitHub:
git clone https://github.com/documenso/documenso.git cd documenso
Step 2: Install Dependencies Install all required npm packages:
This may take several minutes as it installs dependencies for the entire monorepo.
Step 3: Create Environment File Copy the example environment file and customize it:
Edit .env with your configuration:
# Authentication & Encryption NEXTAUTH_SECRET = "your-secret-here" # Generate with: openssl rand -hex 32 NEXT_PRIVATE_ENCRYPTION_KEY = "your-key-here" # Generate with: openssl rand -hex 32 NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY = "your-secondary-key-here" # Generate with: openssl rand -hex 32 # Application URLs NEXT_PUBLIC_WEBAPP_URL = "http://localhost:3000" NEXT_PRIVATE_INTERNAL_WEBAPP_URL = "http://localhost:3000" # Database NEXT_PRIVATE_DATABASE_URL = "postgresql://documenso:password@localhost:5432/documenso" NEXT_PRIVATE_DIRECT_DATABASE_URL = "postgresql://documenso:password@localhost:5432/documenso" # SMTP Configuration NEXT_PRIVATE_SMTP_TRANSPORT = "smtp-auth" NEXT_PRIVATE_SMTP_HOST = "smtp.example.com" NEXT_PRIVATE_SMTP_PORT = 587 NEXT_PRIVATE_SMTP_USERNAME = "your-username" NEXT_PRIVATE_SMTP_PASSWORD = "your-password" NEXT_PRIVATE_SMTP_FROM_NAME = "Documenso" NEXT_PRIVATE_SMTP_FROM_ADDRESS = "noreply@example.com"
Replace all placeholder values with your actual credentials. Never commit the .env file to version control.
Step 4: Setup Database Create a PostgreSQL database for Documenso:
# Using psql psql -U postgres -c "CREATE DATABASE documenso;" psql -U postgres -c "CREATE USER documenso WITH PASSWORD 'your-password';" psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE documenso TO documenso;"
Run database migrations:
npm run prisma:migrate-deploy
To seed the database with test data during development: Step 5: Generate Signing Certificate A signing certificate is required for creating digital signatures. Generate a self-signed certificate:
Generate private key and certificate
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout private.key \ -out certificate.crt \ -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"
Create PKCS12 file
openssl pkcs12 -export -out cert.p12 \ -inkey private.key \ -in certificate.crt \ -passout pass:your-cert-password
Move certificate to secure location
mkdir -p ~/.documenso mv cert.p12 ~/.documenso/ chmod 600 ~/.documenso/cert.p12 rm private.key certificate.crt
Update .env file
Add these lines to your .env: NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH = "/home/yourusername/.documenso/cert.p12" NEXT_PRIVATE_SIGNING_PASSPHRASE = "your-cert-password"
For production use, consider getting a certificate from a trusted Certificate Authority (CA) instead of using a self-signed certificate.
Step 6: Compile Translations Documenso uses Lingui for internationalization. Compile translation files:
npm run translate:compile
Step 7: Build the Application Build all packages and the main application:
The build process may take 2-5 minutes depending on your system.
Step 8: Start Documenso Start the production server:
cd apps/remix npm run start
Documenso will start on http://localhost:3000 (or the port specified in your .env file).
To use a different port, set the PORT environment variable: Running as a System Service For production deployments, run Documenso as a systemd service to ensure it starts automatically.
Create Service File Create /etc/systemd/system/documenso.service:
[Unit] Description =Documenso Document Signing Platform After =network.target postgresql.service [Service] Type =simple User =www-data WorkingDirectory =/var/www/documenso/apps/remix Environment = "PATH=/usr/local/bin:/usr/bin:/bin" Environment = "NODE_ENV=production" ExecStart =/usr/bin/npm run start Restart =always RestartSec =10 StandardOutput =syslog StandardError =syslog SyslogIdentifier =documenso [Install] WantedBy =multi-user.target
Update paths and user names to match your system configuration.
Enable and Start Service # Reload systemd sudo systemctl daemon-reload # Enable service to start on boot sudo systemctl enable documenso # Start the service sudo systemctl start documenso # Check status sudo systemctl status documenso
View Service Logs # View recent logs sudo journalctl -u documenso -n 100 # Follow logs in real-time sudo journalctl -u documenso -f
Development Mode For local development, you can use the development server with hot-reloading:
Quick Start Development The fastest way to start development:
This single command:
Starts Docker services (database, mailserver, S3)
Runs migrations
Seeds the database
Compiles translations
Starts the dev server
Manual Development Setup Or run each step individually:
Start development services
This starts PostgreSQL, Inbucket (mail), and MinIO (S3) in Docker.
Run migrations
npm run prisma:migrate-dev
Access Development Services When running in development mode:
Updating Documenso To update to the latest version:
Backup database
pg_dump documenso > backup- $( date +%Y%m%d ) .sql
Run migrations
npm run prisma:migrate-deploy
Restart service
sudo systemctl restart documenso # Or manually restart your process
Troubleshooting Build Errors If you encounter build errors:
# Clear all caches and rebuild npm run clean npm install npm run build
Database Connection Issues Verify PostgreSQL is running and accessible:
# Test connection psql -U documenso -d documenso -h localhost -c "SELECT 1;"
Check that your NEXT_PRIVATE_DATABASE_URL matches your PostgreSQL configuration.
Environment Variable Issues If environment variables aren’t loading:
# Use the with:env wrapper npm run with:env -- npm run dev
Email Not Sending Test SMTP configuration:
Verify SMTP credentials
Double-check your SMTP host, port, username, and password in .env.
Check SMTP logs
Look for SMTP-related errors in the application logs.
Test with different transport
Try using a different SMTP provider to isolate the issue.
Certificate Errors If you see certificate-related errors:
# Check file exists and has correct permissions ls -la ~/.documenso/cert.p12 # Verify password matches openssl pkcs12 -in ~/.documenso/cert.p12 -noout -passin pass:your-cert-password
Advanced Configuration Using External S3 Storage To use S3 for document storage instead of the database:
NEXT_PUBLIC_UPLOAD_TRANSPORT = "s3" NEXT_PRIVATE_UPLOAD_REGION = "us-east-1" NEXT_PRIVATE_UPLOAD_BUCKET = "documenso-documents" NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID = "your-access-key" NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY = "your-secret-key"
OAuth Authentication Enable Google OAuth:
NEXT_PRIVATE_GOOGLE_CLIENT_ID = "your-client-id" NEXT_PRIVATE_GOOGLE_CLIENT_SECRET = "your-client-secret"
Enable Microsoft OAuth:
NEXT_PRIVATE_MICROSOFT_CLIENT_ID = "your-client-id" NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET = "your-client-secret"
Disable Public Signup For private deployments, disable public user registration:
NEXT_PUBLIC_DISABLE_SIGNUP = "true"
Custom Database Pool For high-traffic deployments, use connection pooling with PgBouncer:
NEXT_PRIVATE_DATABASE_URL = "postgresql://user:pass@pgbouncer:6432/documenso" NEXT_PRIVATE_DIRECT_DATABASE_URL = "postgresql://user:pass@postgres:5432/documenso"
Node.js Memory For large deployments, increase Node.js memory:
NODE_OPTIONS = "--max-old-space-size=4096" npm run start
Database Indexing Ensure all migrations have run to create proper indexes:
npm run prisma:migrate-deploy
Reverse Proxy Use nginx or Caddy as a reverse proxy to:
Handle SSL/TLS termination
Serve static assets efficiently
Enable HTTP/2
Add rate limiting
See the Docker deployment guide for reverse proxy examples.
Next Steps
Environment Variables Complete reference of all configuration options
Email Configuration Configure different email providers
Signing Certificates Learn about production-ready certificates
Monitoring Set up monitoring and logging
