Codakey
Play
← Back to documenso

How to Deploy & Use documenso

Documenso Deployment & Usage Guide

1. Prerequisites

Before deploying Documenso, ensure you have the following installed:

Runtime & Database:

  • Node.js v22 or higher
  • PostgreSQL database (v12+)
  • Docker (optional, for containerized deployment)

Development Tools:

  • Git
  • npm or yarn package manager
  • TypeScript compiler

Optional Services (for full functionality):

  • Stripe account (for payment processing)
  • Email service (SMTP configuration for sending notifications)
  • Object storage (for file uploads, if not using local storage)

2. Installation

Clone the repository and install dependencies:

# Clone the repository
git clone https://github.com/documenso/documenso.git
cd documenso

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local

Using Dev Containers (Recommended for Development): If you have VS Code with Dev Containers extension, you can open the project in a containerized environment by clicking the "Open in Dev Container" badge in the README or using the command palette.

3. Configuration

Edit your .env.local file with the following essential variables:

Database Configuration

# PostgreSQL connection
DATABASE_URL="postgresql://user:password@localhost:5432/documenso"

# Direct database URL (for Prisma)
DIRECT_DATABASE_URL="postgresql://user:password@localhost:5432/documenso"

Application Configuration

# Web application URL
NEXT_PUBLIC_WEBAPP_URL="http://localhost:3000"
NEXT_PRIVATE_WEBAPP_URL="http://localhost:3000"
NEXT_PRIVATE_INTERNAL_WEBAPP_URL="http://localhost:3000"

# Secret keys (generate with `openssl rand -base64 32`)
NEXTAUTH_SECRET="your-secret-key-here"
ENCRYPTION_SECRET="your-encryption-key-here"

# Authentication
NEXTAUTH_URL="http://localhost:3000"

Optional Services

# Email configuration (SMTP)
SMTP_HOST="smtp.example.com"
SMTP_PORT="587"
SMTP_USER="user@example.com"
SMTP_PASSWORD="password"
SMTP_FROM="noreply@example.com"

# Stripe (for payments)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_..."
NEXT_PRIVATE_STRIPE_SECRET_KEY="sk_..."
NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET="whsec_..."

# File storage (local or S3-compatible)
NEXT_PRIVATE_UPLOAD_STORAGE="local"
# For S3:
NEXT_PRIVATE_S3_ACCESS_KEY="..."
NEXT_PRIVATE_S3_SECRET_KEY="..."
NEXT_PRIVATE_S3_BUCKET="..."
NEXT_PRIVATE_S3_REGION="..."
NEXT_PRIVATE_S3_ENDPOINT="..." # Optional for non-AWS S3

Database Setup

Initialize the database schema:

# Generate Prisma client
npx prisma generate

# Run database migrations
npx prisma db push

# Seed the database (optional)
npm run db:seed

4. Build & Run

Development Mode

# Start the development server
npm run dev

# The application will be available at http://localhost:3000

Production Build

# Build the application
npm run build

# Start the production server
npm start

# Or use the standalone server
npm run start:standalone

Running with Docker

# Build the Docker image
docker build -t documenso .

# Run the container
docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:password@host:5432/documenso" \
  -e NEXTAUTH_SECRET="your-secret" \
  documenso

5. Deployment

Platform Recommendations

Vercel (Recommended for Next.js):

  • Supports Next.js out of the box
  • Easy environment variable configuration
  • Automatic preview deployments
  • Connect to Neon PostgreSQL for database

Railway:

  • One-click deployment from GitHub
  • Built-in PostgreSQL database
  • Simple environment management
  • Horizontal scaling options

Docker-based Deployment:

# Build for production
docker build -t documenso:latest .

# Push to container registry
docker tag documenso:latest your-registry/documenso:latest
docker push your-registry/documenso:latest

# Deploy to Kubernetes or Docker Swarm

Traditional Server Deployment:

  1. Set up a PostgreSQL database
  2. Configure a reverse proxy (nginx, Apache)
  3. Set up process management (PM2, systemd)
  4. Configure SSL certificates (Let's Encrypt)

Environment-Specific Considerations

Database:

  • Use managed PostgreSQL services (AWS RDS, Google Cloud SQL, Azure Database)
  • Ensure connection pooling is configured
  • Set up regular backups

File Storage:

  • For production, use S3 or compatible object storage
  • Configure CORS policies appropriately
  • Implement lifecycle policies for old documents

Email:

  • Use transactional email services (SendGrid, Mailgun, AWS SES)
  • Configure SPF, DKIM, and DMARC records
  • Set up email templates in packages/email/templates/

Scaling:

  • The application is stateless; scale horizontally
  • Use Redis for session storage in clustered environments
  • Configure database connection pooling

6. Troubleshooting

Common Issues

Database Connection Errors:

# Verify database is running
psql -h localhost -U postgres -d documenso

# Reset database (development only)
npx prisma migrate reset

Build Failures:

# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check TypeScript errors
npx tsc --noEmit

PDF Generation Issues:

  • Ensure fonts are available at /fonts/caveat.ttf and /fonts/noto-sans.ttf
  • Check that PDF-Lib dependencies are properly installed
  • Verify file permissions for upload directory

Email Not Sending:

  • Check SMTP configuration in environment variables
  • Verify email templates are compiled: npm run email:dev
  • Check server logs for email sending errors

Authentication Problems:

  • Ensure NEXTAUTH_SECRET is set and consistent across instances
  • Verify NEXTAUTH_URL matches your deployment URL
  • Check database for user sessions

Performance Issues:

# Monitor database queries
npx prisma studio

# Check memory usage
node --inspect server.js

# Enable PDF debug mode (if experiencing PDF issues)
DEBUG_PDF_INSERT="1"

Logging and Debugging

Enable detailed logging by setting:

LOG_LEVEL="debug"
NEXT_PUBLIC_LOG_LEVEL="debug"

Check application logs:

# Development logs
npm run dev 2>&1 | tee app.log

# Production logs
journalctl -u documenso.service -f

Getting Help

Note: This is a self-hosted solution. For enterprise support or managed hosting, contact the Documenso team through their website.

← Project overviewView alternatives to documenso →