Skip to content
Klutch.sh Docs

Deploying Documenso

Introduction

Documenso is a powerful, free, and open-source alternative to DocuSign for digital document signing and management. Built with modern web technologies including Next.js, TypeScript, and tRPC, Documenso provides an intuitive interface for creating, signing, and managing legally binding digital documents. It’s perfect for businesses, teams, and individuals who need a secure, self-hosted solution for document workflows, electronic signatures, contract management, and compliance documentation.

Deploying Documenso on Klutch.sh gives you a production-ready, scalable platform with automated deployments from GitHub, persistent storage for signed documents and attachments, and reliable infrastructure for hosting your document signing workflows. Whether you’re building an internal contract signing system, creating a white-label document platform, or managing customer agreements, this comprehensive guide walks you through deploying Documenso using Docker to ensure a reproducible, secure, and maintainable setup.

This guide covers everything you need to successfully deploy Documenso on Klutch.sh: from creating your production-ready Dockerfile to configuring PostgreSQL database connections, setting up persistent volumes for document storage, managing environment variables securely, configuring authentication providers, implementing email notifications, and following best practices for security, performance, and compliance with digital signature regulations.

Prerequisites

Before you begin deploying Documenso on Klutch.sh, ensure you have the following:

  • A Klutch.sh account (access the dashboard here)
  • A GitHub repository for your Documenso deployment project
  • Basic familiarity with Docker, environment variables, and database management
  • A PostgreSQL database (you can provision one on Klutch.sh or use an external managed database service)
  • An SMTP email service for sending document notifications and verification emails
  • Understanding of Next.js applications (helpful but not required)

What You’ll Deploy

By the end of this guide, you’ll have:

  • A fully functional Documenso document signing platform running on Klutch.sh
  • Persistent storage for uploaded documents, signed PDFs, and application data
  • PostgreSQL database connectivity for storing documents, signatures, and user data
  • Secure environment variable configuration for credentials and secrets
  • Production-ready setup with proper authentication and email notifications
  • A Docker-based deployment that’s reproducible and easy to maintain
  • HTTP traffic routing configured properly for web access
  • Integration with email service for document notifications and workflows

Understanding Documenso Architecture

Documenso is built with modern web technologies and requires:

  • Node.js 18 or higher with npm/yarn for package management
  • Next.js 13+ for the web application framework
  • PostgreSQL 14+ database for storing documents, users, signatures, and metadata
  • File storage for uploaded documents, signed PDFs, and attachments
  • Email service (SMTP) for sending document invitations, reminders, and notifications
  • Authentication provider (NextAuth.js) for user management and security
  • PDF processing capabilities for document rendering and signature placement

The application runs on port 3000 by default when using Next.js. For Klutch.sh deployments with HTTP traffic, you’ll configure the internal port to 3000, and traffic will be routed from external port 8000 to your container.

1. Prepare Your Documenso Repository

    1. Create a new GitHub repository for your Documenso deployment.

    2. In your repository root, you’ll create a Dockerfile that defines the container image for Documenso. This ensures reproducible builds and makes deployment consistent.

    3. Keep sensitive data (database credentials, encryption keys, email passwords) out of your repository. We’ll use Klutch.sh environment variables to manage secrets securely.

    4. Organize your repository structure:

      documenso-deployment/
      ├── Dockerfile
      ├── .dockerignore
      ├── .env.example
      ├── docker-compose.yml (for local development only)
      └── README.md

    5. Create a .dockerignore file to exclude unnecessary files from the Docker build:

      .git
      .github
      .env
      .env.*
      node_modules
      .next
      out
      dist
      .vercel
      .turbo
      *.log
      npm-debug.log*
      yarn-debug.log*
      yarn-error.log*
      .DS_Store
      coverage
      .nyc_output

For more details on setting up your repository and connecting to GitHub, refer to the Klutch.sh Quick Start Guide.

2. Sample Dockerfile for Documenso

Below is a production-ready Dockerfile that sets up Documenso with all required dependencies, proper build configuration, and optimized multi-stage build for smaller image size. This Dockerfile uses the official Documenso approach, building from source and configuring Next.js to serve the application.

# Stage 1: Dependencies
FROM node:18-alpine AS deps
WORKDIR /app


# Install dependencies needed for native module compilation during package installation
RUN apk add --no-cache libc6-compat python3 make g++


# Copy package files
COPY package.json yarn.lock ./


# Install dependencies
RUN yarn install --frozen-lockfile


# Stage 2: Builder
FROM node:18-alpine AS builder
WORKDIR /app


# Copy dependencies from deps stage
COPY --from=deps /app/node_modules ./node_modules


# Copy application source code
COPY . .


# Set build-time environment variables
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production


# Build the application
RUN yarn build


# Stage 3: Runner
FROM node:18-alpine AS runner
WORKDIR /app


ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1


# Create a non-root user
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs


# Copy necessary files from builder
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static


# Create directory for uploaded documents
RUN mkdir -p /app/uploads && chown -R nextjs:nodejs /app/uploads


# Set proper permissions
RUN chown -R nextjs:nodejs /app


USER nextjs


EXPOSE 3000


ENV PORT=3000
ENV HOSTNAME="0.0.0.0"


CMD ["node", "server.js"]

Dockerfile Explanation

  • Multi-Stage Build: Uses three stages to minimize final image size (deps, builder, runner)
  • Alpine Linux: Uses lightweight Alpine Linux base for smaller images
  • Node.js 18: Uses Node.js 18 LTS version for compatibility with Documenso
  • Security: Runs as non-root user (nextjs) for improved security
  • Next.js Standalone: Uses Next.js standalone output for optimized production builds (requires next.config.js configuration)
  • Port Configuration: Exposes port 3000 for HTTP traffic
  • Document Storage: Creates uploads directory for document files
  • Build Optimization: Excludes unnecessary files via .dockerignore to reduce build context size

3. Next.js Configuration

Create or ensure your next.config.js is configured for standalone output. Create this file in your repository root:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
  reactStrictMode: true,
  swcMinify: true,
  images: {
    domains: ['localhost'],
  },
  experimental: {
    serverActions: true,
  },
}


module.exports = nextConfig

Configuration Explanation

  • Standalone Output: Enables standalone mode for optimized Docker deployments
  • React Strict Mode: Enables strict mode for better development experience
  • SWC Minification: Uses faster SWC compiler for minification
  • Server Actions: Enables Next.js 13+ server actions for form handling
  • Image Optimization: Configures allowed image domains

4. Persistent Storage Configuration

Documenso requires persistent storage for uploaded documents, signed PDFs, user attachments, and application data. On Klutch.sh, you’ll attach a persistent volume to store this critical data.

    1. In the Klutch.sh dashboard, navigate to your app configuration.

    2. Under the Volumes section, add a new persistent volume.

    3. Set the mount path to /app/uploads for storing uploaded documents, signed PDFs, and attachments.

    4. Set the volume size based on your expected storage needs (start with 10GB and scale up as needed based on document volume).

    5. Optionally, add another volume for application logs at /app/.next/cache if you want to persist build caches separately.

Important: The mount path is where your document data will persist across deployments. Documenso stores all uploaded documents, signed PDFs, and user attachments in the uploads directory. Ensure this volume has sufficient space for your document management needs.

For more information about volumes, see the Klutch.sh Volumes Guide.

5. Database Setup

Documenso requires a PostgreSQL database to store documents, users, signatures, workflows, and metadata. You can use a managed PostgreSQL service or deploy your own PostgreSQL container.

Option A: Using an External PostgreSQL Service

If you’re using a managed PostgreSQL service (like AWS RDS, DigitalOcean Managed Databases, Supabase, or Neon):

    1. Create a new PostgreSQL database instance through your provider.

    2. Create a dedicated database for Documenso (e.g., documenso_db).

    3. Create a dedicated PostgreSQL user with full privileges on the Documenso database:

      CREATE DATABASE documenso_db;
      CREATE USER documenso_user WITH ENCRYPTED PASSWORD 'your_secure_password';
      GRANT ALL PRIVILEGES ON DATABASE documenso_db TO documenso_user;

    4. Note the database connection URL in the format:

      postgresql://documenso_user:your_secure_password@your-postgres-host.example.com:5432/documenso_db

    5. Ensure network connectivity between your Klutch.sh app and the database (configure security groups/firewall rules as needed).

Option B: Using Klutch.sh PostgreSQL

For deploying PostgreSQL on Klutch.sh, refer to the PostgreSQL deployment guide.

Database Initialization

Documenso uses Prisma for database management and will automatically run migrations on first startup. Ensure your database is accessible before deploying the application.

6. Environment Variables Configuration

Configure the following environment variables in the Klutch.sh dashboard under your app’s settings. These variables are essential for Documenso to connect to the database, send emails, and operate correctly.

Required Environment Variables

Terminal window
# Application URL
NEXT_PUBLIC_WEBAPP_URL=https://example-app.klutch.sh
NEXTAUTH_URL=https://example-app.klutch.sh


# Secret for NextAuth.js (generate with: openssl rand -base64 32)
NEXTAUTH_SECRET=your_32_character_random_secret_here


# Database Connection
DATABASE_URL=postgresql://documenso_user:password@your-postgres-host:5432/documenso_db


# Encryption Key (generate with: openssl rand -hex 32)
NEXT_PRIVATE_ENCRYPTION_KEY=your_64_character_hex_encryption_key
NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY=your_64_character_hex_secondary_key


# Email Configuration (SMTP)
NEXT_PRIVATE_SMTP_HOST=smtp.example.com
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME=your_smtp_username
NEXT_PRIVATE_SMTP_PASSWORD=your_smtp_password
NEXT_PRIVATE_SMTP_FROM_ADDRESS=noreply@example.com
NEXT_PRIVATE_SMTP_FROM_NAME=Documenso


# Signing Configuration
NEXT_PUBLIC_UPLOAD_TRANSPORT=local
NEXT_PRIVATE_SIGNING_TRANSPORT=local

Environment Variables Explanation

  • NEXT_PUBLIC_WEBAPP_URL: The public URL where your Documenso instance will be accessible
  • NEXTAUTH_URL: Same as WEBAPP_URL, used by NextAuth.js for OAuth callbacks
  • NEXTAUTH_SECRET: Secret key used by NextAuth.js for JWT encryption (must be at least 32 characters)
  • DATABASE_URL: PostgreSQL connection string in the standard format
  • ENCRYPTION_KEY: Used for encrypting sensitive data in the database (generate a secure random key)
  • ENCRYPTION_SECONDARY_KEY: Secondary key for key rotation and additional encryption layer
  • SMTP_* variables**: Configuration for sending email notifications, invitations, and reminders
  • UPLOAD_TRANSPORT: Set to “local” for local file storage (use “s3” for AWS S3 integration)
  • SIGNING_TRANSPORT: Set to “local” for local signature storage

Optional Environment Variables

Terminal window
# OAuth Providers (optional but recommended for enterprise)
NEXT_PRIVATE_GOOGLE_CLIENT_ID=your_google_client_id
NEXT_PRIVATE_GOOGLE_CLIENT_SECRET=your_google_client_secret


# S3 Storage (alternative to local storage)
NEXT_PRIVATE_UPLOAD_TRANSPORT=s3
NEXT_PRIVATE_UPLOAD_ENDPOINT=https://s3.amazonaws.com
NEXT_PRIVATE_UPLOAD_REGION=us-east-1
NEXT_PRIVATE_UPLOAD_BUCKET=documenso-uploads
NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID=your_s3_access_key
NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY=your_s3_secret_key


# Webhook Configuration
NEXT_PUBLIC_ENABLE_WEBHOOKS=true


# Feature Flags
NEXT_PUBLIC_ALLOW_SIGNUP=false
NEXT_PUBLIC_DISABLE_SIGNUP=true


# Logging
NEXT_PRIVATE_LOG_LEVEL=info

Security Best Practice: Mark all sensitive values like NEXTAUTH_SECRET, DATABASE_URL, ENCRYPTION_KEY, and SMTP passwords as secrets in Klutch.sh to prevent them from being logged or displayed in the UI.

Generating Secure Keys

Generate secure random keys using these commands:

Terminal window
# Generate NEXTAUTH_SECRET (32 characters base64)
openssl rand -base64 32


# Generate ENCRYPTION_KEY (64 characters hex)
openssl rand -hex 32

7. Deploying to Klutch.sh

Now that you have your repository configured with the Dockerfile, Next.js configuration, and understanding of the required environment variables, let’s deploy Documenso to Klutch.sh.

    1. Push your repository to GitHub: Ensure your Dockerfile, next.config.js, .dockerignore, and README.md are committed and pushed to your GitHub repository.

    2. Access the Klutch.sh dashboard: Log in to klutch.sh/app.

    3. Create a new project (if you haven’t already): Projects help organize related apps and resources.

    4. Create a new app:

      • Click “New App” or “Create App”
      • Select your GitHub repository containing the Documenso Dockerfile
      • Klutch.sh will automatically detect the Dockerfile in your root directory

    5. Configure the app settings:

      • Name: Give your app a meaningful name (e.g., “documenso-signing”)
      • Branch: Select the Git branch to deploy (usually main or master)

    6. Set up persistent volumes:

      • Navigate to the Volumes section in the app configuration
      • Add a volume with mount path: /app/uploads
      • Set size: Start with 10GB (adjust based on your document storage needs)

    7. Configure environment variables:

      • Add all the required environment variables listed in Section 6
      • Mark sensitive values (NEXTAUTH_SECRET, DATABASE_URL, ENCRYPTION_KEY, SMTP passwords) as secrets
      • Ensure NEXT_PUBLIC_WEBAPP_URL and NEXTAUTH_URL match your intended domain (e.g., https://example-app.klutch.sh)

    8. Configure network settings:

      • Select HTTP traffic type (not TCP)
      • Set the internal port to 3000 (the port Next.js listens on inside the container)
      • External traffic from port 8000 will be automatically routed to your container’s port 3000

    9. Review and deploy:

      • Review all settings to ensure everything is configured correctly
      • Click “Create” or “Deploy” to start the build and deployment process

    10. Monitor the deployment:

      • Watch the build logs to ensure the Docker image builds successfully
      • The build process may take 5-10 minutes for the first deployment
      • Once deployed, the app status should show as “Running”
      • Check the runtime logs for any errors or database migration messages

    11. Verify database migrations:

      • Documenso uses Prisma and will automatically run database migrations on startup
      • Check the logs for “Database migrations completed” or similar messages
      • If migrations fail, verify your DATABASE_URL is correct and the database is accessible

    12. Access your Documenso instance:

      • Navigate to your app URL (e.g., https://example-app.klutch.sh)
      • You should see the Documenso login/signup page
      • Create your admin account to start using the platform

For more detailed deployment instructions, see the Klutch.sh Quick Start Guide.

8. Initial Documenso Setup

After your deployment is successful and the app is running:

    1. Navigate to your Documenso URL (e.g., https://example-app.klutch.sh).

    2. If signup is enabled (NEXT_PUBLIC_ALLOW_SIGNUP=true), you’ll see the registration page. Create your admin account:

      • Enter your email address
      • Choose a strong password
      • Verify your email (if email is configured)

    3. Important Security Steps:

      • After creating your admin account, consider disabling public signups by setting:
        Terminal window
        NEXT_PUBLIC_ALLOW_SIGNUP=false
        NEXT_PUBLIC_DISABLE_SIGNUP=true
      • Create additional user accounts through the admin interface
      • Configure two-factor authentication if available

    4. Configure application settings:

      • Navigate to Settings → Profile
      • Update your profile information
      • Configure notification preferences
      • Set up email signature and branding

    5. Set up document templates (optional):

      • Create reusable document templates
      • Configure default signing workflows
      • Set up automated reminders

    6. Test the document workflow:

      • Upload a test PDF document
      • Add signers with email addresses
      • Configure signature fields and placement
      • Send the document for signing
      • Verify email notifications are sent correctly

    7. Configure team settings (if applicable):

      • Invite team members
      • Set up roles and permissions
      • Configure team branding
      • Set document retention policies

9. Email Configuration

Proper email configuration is critical for Documenso to function correctly. Documents are sent to signers via email, and notifications keep users informed of document status.

SMTP Configuration

Documenso supports standard SMTP email services. Popular options include:

  • SendGrid: Reliable, generous free tier
  • Mailgun: Developer-friendly, good deliverability
  • Amazon SES: Cost-effective for high volume
  • Postmark: Excellent for transactional emails
  • Gmail SMTP: Works for testing but not recommended for production

Example SMTP Configurations

SendGrid:

Terminal window
NEXT_PRIVATE_SMTP_HOST=smtp.sendgrid.net
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME=apikey
NEXT_PRIVATE_SMTP_PASSWORD=your_sendgrid_api_key
NEXT_PRIVATE_SMTP_FROM_ADDRESS=documents@yourdomain.com

Mailgun:

Terminal window
NEXT_PRIVATE_SMTP_HOST=smtp.mailgun.org
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME=postmaster@yourdomain.com
NEXT_PRIVATE_SMTP_PASSWORD=your_mailgun_password
NEXT_PRIVATE_SMTP_FROM_ADDRESS=documents@yourdomain.com

Testing Email Configuration

After configuring email, test it by:

    1. Creating a test document
    2. Adding yourself as a signer
    3. Sending the document
    4. Checking your email inbox for the signing invitation
    5. Verifying all links in the email work correctly

If emails aren’t being delivered:

  • Check SMTP credentials are correct
  • Verify your email provider allows connections from your Klutch.sh app IP
  • Check spam/junk folders
  • Review application logs for email sending errors
  • Ensure your FROM address is verified with your email provider

10. Custom Domain Configuration

To use a custom domain with your Documenso instance instead of the default Klutch.sh subdomain:

    1. In the Klutch.sh dashboard, navigate to your Documenso app.

    2. Go to the Domains section and add your custom domain (e.g., sign.example.com).

    3. Klutch.sh will provide you with DNS configuration instructions:

      • Add a CNAME record pointing to your Klutch.sh app URL, or
      • Add an A record pointing to the provided IP address

    4. Update the environment variables to match your custom domain:

      Terminal window
      NEXT_PUBLIC_WEBAPP_URL=https://sign.example.com
      NEXTAUTH_URL=https://sign.example.com

    5. Restart your application to apply the new URL configuration.

    6. Wait for DNS propagation (can take up to 48 hours but usually much faster).

    7. Klutch.sh automatically provisions and manages SSL/TLS certificates for your custom domain.

    8. Once DNS propagates, access Documenso at your custom domain with HTTPS enabled.

For more information, see the Custom Domains Guide.

11. Backup and Maintenance

Regular backups are essential for protecting your documents, signatures, and user data.

Database Backups

Use pg_dump to create regular PostgreSQL database backups:

Terminal window
pg_dump -h $DB_HOST -U $DB_USER -d $DB_NAME -F c -f documenso-backup-$(date +%F).dump

Automate this with a cron job or scheduled task, and store backups in object storage (S3, Backblaze B2, etc.).

Document Storage Backups

The persistent volume at /app/uploads contains all uploaded documents, signed PDFs, and attachments. Consider:

  • Taking regular snapshots of the volume through your hosting provider
  • Syncing the volume to object storage (S3) periodically
  • Implementing a backup rotation policy (daily, weekly, monthly)
  • Testing restoration procedures regularly

Restoration Process

To restore from a backup:

    1. Restore the database:

      Terminal window
      pg_restore -h $DB_HOST -U $DB_USER -d $DB_NAME -c documenso-backup-2024-01-15.dump

    2. Restore uploaded documents to the persistent volume:

      Terminal window
      # From S3 backup
      aws s3 sync s3://your-backup-bucket/uploads/ /app/uploads/
      

      # Or from local backup
      rsync -avz /backup/uploads/ /app/uploads/

    3. Restart the application to pick up the restored data.

    4. Verify data integrity and test document access.

12. Security Best Practices

Application Security

  • Strong encryption keys: Use cryptographically secure random keys for NEXTAUTH_SECRET and ENCRYPTION_KEY
  • Disable public signup: Set NEXT_PUBLIC_ALLOW_SIGNUP=false for internal/enterprise deployments
  • Enable two-factor authentication: Configure 2FA for admin accounts
  • Regular updates: Keep Documenso updated to the latest version for security patches
  • Use strong passwords: Enforce password complexity requirements
  • Audit logging: Enable and review audit logs for sensitive operations
  • Rate limiting: Implement rate limiting on authentication endpoints

Database Security

  • Use strong database passwords with at least 20 characters (letters, numbers, symbols)
  • Limit database access: Only allow connections from your Documenso app
  • Enable SSL/TLS for database connections when possible
  • Regular backups: Automate database backups to prevent data loss
  • Database encryption: Use encryption at rest for sensitive document data
  • Minimal privileges: Grant only necessary permissions to database users

Infrastructure Security

  • HTTPS only: Always use HTTPS for production deployments (automatic with Klutch.sh)
  • Environment variables: Never commit secrets to your repository
  • Secure email: Use authenticated SMTP with TLS/SSL
  • Document retention: Implement policies for document deletion and archival
  • Monitor logs: Regularly review application and access logs for suspicious activity
  • Security headers: Configure proper security headers (CSP, HSTS, X-Frame-Options)

Compliance Considerations

For legally binding digital signatures, ensure:

  • Audit trails: Maintain complete audit logs of all signature events
  • Timestamping: Use reliable timestamps for signature events
  • Identity verification: Implement proper signer authentication
  • Document integrity: Use cryptographic hashes to verify document hasn’t been modified
  • Legal compliance: Understand regulations in your jurisdiction (ESIGN Act, eIDAS, etc.)
  • Data privacy: Comply with GDPR, CCPA, and other privacy regulations
  • Record retention: Follow industry-specific requirements for document retention

13. Performance Optimization

Application Optimization

  • Image optimization: Use Next.js Image component for optimized image loading
  • Database indexing: Ensure proper database indexes for frequently queried fields
  • Caching: Implement Redis for session storage and caching
  • CDN integration: Use CDN for serving static assets
  • Code splitting: Take advantage of Next.js automatic code splitting

Infrastructure Optimization

  • Scale vertically: Increase CPU and memory if the app becomes slow under load
  • Database connection pooling: Configure appropriate connection pool size
  • Database optimization: Use appropriate PostgreSQL configuration for your workload
  • Monitoring: Set up monitoring for CPU, memory, database connections, and response time metrics

Database Performance

-- Add indexes for common queries
CREATE INDEX idx_documents_user_id ON documents(user_id);
CREATE INDEX idx_documents_status ON documents(status);
CREATE INDEX idx_signatures_document_id ON signatures(document_id);
CREATE INDEX idx_signatures_user_id ON signatures(user_id);

Scaling Considerations

For high-volume Documenso deployments:

  • Consider horizontal scaling with multiple app instances behind a load balancer
  • Use external session storage (Redis) for session persistence across instances
  • Configure S3 storage for documents to share files across instances
  • Implement database read replicas for read-heavy workloads
  • Use a CDN for serving signed documents
  • Implement job queues for asynchronous document processing

14. Troubleshooting

Common Issues and Solutions

Issue: “Database connection failed” Error

Solution:

  • Verify DATABASE_URL is correctly formatted
  • Check network connectivity between app and database
  • Ensure PostgreSQL is running and accessible
  • Test connection manually: psql $DATABASE_URL -c "SELECT 1"
  • Check database credentials and permissions

Issue: “NextAuth.js configuration error”

Solution:

  • Ensure NEXTAUTH_SECRET is set (minimum 32 characters)
  • Verify NEXTAUTH_URL matches your application URL exactly
  • Check that both HTTP and HTTPS URLs are consistent
  • Clear browser cookies and try again

Issue: Email not sending

Solution:

  • Verify SMTP credentials in environment variables
  • Check SMTP host and port are correct
  • Test SMTP connection: telnet $SMTP_HOST $SMTP_PORT
  • Ensure FROM email address is verified with your provider
  • Check application logs for email sending errors
  • Verify your email provider allows connections from your app

Issue: “Encryption key invalid” Error

Solution:

  • Generate new encryption keys using openssl rand -hex 32
  • Ensure keys are exactly 64 hex characters
  • Don’t change encryption keys after storing encrypted data (or data will be unreadable)
  • Set both primary and secondary encryption keys

Issue: File upload fails

Solution:

  • Check persistent volume is mounted correctly at /app/uploads
  • Verify permissions: chown -R nextjs:nodejs /app/uploads
  • Check disk space on the persistent volume
  • Review file size limits in your configuration
  • Check application logs for upload errors

Issue: 502 Bad Gateway or App Not Responding

Solution:

  • Check that Next.js server is running inside the container
  • Verify internal port is set to 3000
  • Review application logs for startup errors
  • Ensure database migrations completed successfully
  • Check environment variables are set correctly

Debugging Tips

View Application Logs:

Access logs through the Klutch.sh dashboard or by connecting to the container.

Check Database Connection:

Terminal window
# Test PostgreSQL connection
psql $DATABASE_URL -c "SELECT version();"

Verify Environment Variables:

Terminal window
# Inside the container
env | grep NEXT

Check Prisma Migrations:

Terminal window
# View migration status
npx prisma migrate status


# Manually run migrations if needed
npx prisma migrate deploy

Clear Next.js Cache:

Terminal window
# Delete .next directory and rebuild
rm -rf .next
npm run build

15. Updating Documenso

To update Documenso to a newer version:

    1. Check the Documenso releases page for the latest version and changelog.

    2. Review breaking changes and migration notes in the release notes.

    3. Update your repository:

      • If using the official Documenso repository, update the Git submodule or pull the latest changes
      • If using a custom repository, merge or cherry-pick the updates

    4. Update dependencies in package.json if needed:

      Terminal window
      npm update
      # or
      yarn upgrade

    5. Commit and push the changes to your GitHub repository.

    6. Klutch.sh will automatically trigger a new build with the updated version.

    7. Database migrations will run automatically on startup via Prisma.

    8. Test the updated version thoroughly:

      • Verify document upload and signing workflow
      • Test email notifications
      • Check user authentication
      • Verify document downloads

    9. Monitor logs during and after the update for any issues.

    10. Keep backups of your database and documents before major updates.

Important: Always test updates in a staging environment before deploying to production. Major version updates may require manual intervention or configuration changes.

16. Advanced Features and Integrations

OAuth Integration

Enable OAuth providers for easier authentication:

Terminal window
# Google OAuth
NEXT_PRIVATE_GOOGLE_CLIENT_ID=your_google_client_id
NEXT_PRIVATE_GOOGLE_CLIENT_SECRET=your_google_client_secret


# GitHub OAuth
NEXT_PRIVATE_GITHUB_CLIENT_ID=your_github_client_id
NEXT_PRIVATE_GITHUB_CLIENT_SECRET=your_github_client_secret

S3 Storage Integration

For production deployments with multiple instances, use S3 for document storage:

Terminal window
NEXT_PRIVATE_UPLOAD_TRANSPORT=s3
NEXT_PRIVATE_UPLOAD_ENDPOINT=https://s3.amazonaws.com
NEXT_PRIVATE_UPLOAD_REGION=us-east-1
NEXT_PRIVATE_UPLOAD_BUCKET=documenso-documents
NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID=your_aws_access_key
NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY=your_aws_secret_key

Webhook Integration

Enable webhooks to integrate Documenso with other systems:

Terminal window
NEXT_PUBLIC_ENABLE_WEBHOOKS=true

Configure webhooks in the application to notify external systems when:

  • Documents are signed
  • Signature requests are sent
  • Documents are completed
  • Signing deadlines are approaching

API Access

Documenso provides API endpoints for programmatic access:

  • Document creation and management
  • Signature field configuration
  • User management
  • Webhook configuration

Refer to the Documenso API documentation for details.

Resources

Deploying Documenso on Klutch.sh provides you with a robust, scalable platform for managing digital document signing workflows. With persistent volumes for documents, PostgreSQL database integration, and automated deployments from GitHub, you have a production-ready setup that’s easy to maintain and scale. The Docker-based approach ensures consistency across environments and makes updates straightforward. Whether you’re building an internal contract signing system, creating a white-label document platform, or managing customer agreements, Documenso on Klutch.sh gives you the reliability, security, and features you need for legally compliant digital signature workflows.