Updating Documenso

Overview

Regular updates ensure your Documenso instance stays secure, stable, and feature-rich. This guide covers update procedures for both Docker and manual deployments.

Always backup your database and files before performing updates. See the Backups guide for details.

Version Information

Documenso follows semantic versioning (MAJOR.MINOR.PATCH):

Major versions (e.g., 1.x to 2.x): Breaking changes, may require migration steps
Minor versions (e.g., 2.1 to 2.2): New features, backward compatible
Patch versions (e.g., 2.1.0 to 2.1.1): Bug fixes, security patches

Current version information is available at:

GitHub releases: https://github.com/documenso/documenso/releases
In-app: Check the footer of your Documenso instance

Pre-Update Checklist

Before updating, complete these steps:

Review release notes

Check the GitHub releases page for:

Breaking changes
New environment variables
Database migration notes
Special upgrade instructions

Backup your data

Create a complete backup of:

PostgreSQL database
Document files (S3 bucket or database)
Configuration files (.env, docker-compose.yml)
SSL certificates and signing certificates

Check system requirements

Verify your system meets the requirements for the new version:

Node.js version (currently v22 or above)
PostgreSQL version compatibility
Available disk space
Memory requirements

Plan maintenance window

Schedule the update during low-traffic periods. Typical update time:

Small patches: 5-10 minutes downtime
Minor versions: 10-20 minutes downtime
Major versions: 30-60 minutes downtime (varies by database size)

Docker Updates

Using Docker Compose

For Docker Compose deployments, follow these steps:

# 1. Navigate to your Documenso directory
cd /path/to/documenso

# 2. Stop the running containers
docker compose down

# 3. Backup your database (see Backups guide)
docker exec documenso-db pg_dump -U documenso documenso > backup-$(date +%Y%m%d-%H%M%S).sql

# 4. Pull the latest image
docker compose pull

# 5. Start the containers
# Database migrations run automatically via the start.sh script
docker compose up -d

# 6. Check the logs for any errors
docker compose logs -f documenso

Database migrations run automatically when the container starts (via /app/start.sh). You’ll see “Running database migrations…” in the logs.

Using Docker Run

If you’re using docker run instead of Docker Compose:

# 1. Stop the current container
docker stop documenso

# 2. Backup your database
docker exec documenso-db pg_dump -U documenso documenso > backup-$(date +%Y%m%d-%H%M%S).sql

# 3. Pull the latest image
docker pull documenso/documenso:latest

# 4. Remove the old container (data is persisted in volumes)
docker rm documenso

# 5. Start a new container with the same configuration
docker run -d \
  --name documenso \
  --env-file .env \
  -p 3000:3000 \
  -v documenso-data:/app/data \
  documenso/documenso:latest

# 6. Check the logs
docker logs -f documenso

Pinning to Specific Versions

Instead of using :latest, pin to specific versions for predictable updates:

services:
  documenso:
    image: documenso/documenso:2.7.0  # Specific version
    # or
    image: documenso/documenso:2.7    # Minor version (gets latest patch)

Update your docker-compose.yml to the desired version, then run:

docker compose pull
docker compose up -d

Manual/Bare-Metal Updates

For manual installations without Docker:

# 1. Navigate to your Documenso directory
cd /path/to/documenso

# 2. Stop the application
pm2 stop documenso  # or systemctl stop documenso

# 3. Backup your database
pg_dump -U documenso documenso > backup-$(date +%Y%m%d-%H%M%S).sql

# 4. Pull the latest code
git fetch origin
git checkout main
git pull origin main

# Or checkout a specific version
# git checkout v2.7.0

# 5. Install dependencies
npm ci

# 6. Run database migrations
npm run prisma:migrate-deploy

# 7. Rebuild the application
npm run build

# 8. Start the application
pm2 start documenso  # or systemctl start documenso

# 9. Verify the update
curl http://localhost:3000/api/health

Kubernetes Updates

For Kubernetes deployments:

# 1. Update the image version in your deployment manifest
kubectl set image deployment/documenso \
  documenso=documenso/documenso:2.7.0

# Or edit the deployment directly
kubectl edit deployment documenso

# 2. Monitor the rollout
kubectl rollout status deployment/documenso

# 3. Check pod logs
kubectl logs -f deployment/documenso

# 4. Verify the health endpoint
kubectl port-forward svc/documenso 3000:3000
curl http://localhost:3000/api/health

Rollback in Kubernetes

If the update fails:

# View rollout history
kubectl rollout history deployment/documenso

# Rollback to the previous version
kubectl rollout undo deployment/documenso

# Or rollback to a specific revision
kubectl rollout undo deployment/documenso --to-revision=2

Database Migrations

How Migrations Work

Documenso uses Prisma for database migrations. The migration process:

Docker: Migrations run automatically via the startup script at /app/start.sh:28
Manual: You must run migrations manually before starting the app

Migrations are located in packages/prisma/migrations/. Each migration is timestamped and named descriptively.

Manual Migration Commands

# Run pending migrations (production)
npm run prisma:migrate-deploy

# Check migration status
npx prisma migrate status --schema ./packages/prisma/schema.prisma

# Resolve failed migrations (use with caution)
npx prisma migrate resolve --applied [migration_name] --schema ./packages/prisma/schema.prisma

Never modify migration files after they’ve been applied to production. If a migration fails, resolve it forward by creating a new migration.

Migration Failures

If a migration fails:

Check the error message in the logs
Common issues:
- Timeout: Large tables may need increased timeout settings
- Constraint violation: Data conflicts with new constraints
- Permissions: Database user lacks necessary privileges
Resolution steps:

# Check which migrations have been applied
npx prisma migrate status --schema ./packages/prisma/schema.prisma

# If the migration is partially applied, mark it as rolled back
npx prisma migrate resolve --rolled-back [migration_name] --schema ./packages/prisma/schema.prisma

# Fix the underlying issue (data, permissions, etc.)

# Retry the migration
npm run prisma:migrate-deploy

Post-Update Verification

After updating, verify the installation:

Health Checks

# Check overall health
curl http://localhost:3000/api/health

# Expected response:
{
  "status": "ok",
  "timestamp": "2026-03-04T12:00:00.000Z",
  "checks": {
    "database": { "status": "ok" },
    "certificate": { "status": "ok" }
  }
}

Functional Tests

Login: Verify you can log in with existing credentials
Document access: Open an existing document to verify data integrity
New document: Upload and send a test document
Signature: Sign a test document to verify signing certificates work
Webhooks: Check webhook delivery (if configured)
API: Test API endpoints if you have integrations

Check Logs for Errors

# Docker
docker compose logs documenso --tail=100

# Systemd
journalctl -u documenso -n 100 --no-pager

# PM2
pm2 logs documenso --lines 100

Look for:

Database connection errors
Certificate loading issues
Migration warnings
Email service failures

Rollback Procedures

If an update causes issues, rollback to the previous version:

Docker Rollback

# 1. Stop the containers
docker compose down

# 2. Update docker-compose.yml to the previous version
# Change: image: documenso/documenso:2.7.0
# To:     image: documenso/documenso:2.6.5

# 3. If database migrations were run, restore the backup
docker exec -i documenso-db psql -U documenso documenso < backup-20260304-120000.sql

# 4. Start the containers
docker compose up -d

Manual Rollback

# 1. Stop the application
pm2 stop documenso

# 2. Checkout the previous version
git checkout v2.6.5

# 3. Restore the database backup
psql -U documenso documenso < backup-20260304-120000.sql

# 4. Reinstall dependencies
npm ci

# 5. Rebuild
npm run build

# 6. Start the application
pm2 start documenso

Database rollbacks can result in data loss if new data was created between the update and rollback. Only rollback as a last resort.

Update Best Practices

Test updates in a staging environment

Before updating production:

Clone your production environment
Restore a recent backup to staging
Test the update process
Verify all functionality
Only then update production

Keep dependencies updated

Beyond Documenso itself, maintain:

PostgreSQL: Keep within supported versions
Node.js: Update to the latest LTS version (currently v22+)
Docker: Update Docker Engine and Compose
OS packages: Regular security updates

Monitor for security releases

Subscribe to security notifications:

GitHub: Watch the repository and enable security alerts
Discord: Join the Documenso Discord
RSS: Subscribe to the releases feed

Automate updates (with caution)

For patch releases, consider automation:

# Example: Watchtower for Docker (auto-updates containers)
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup \
  --interval 86400 \
  documenso

Only automate patch releases. Always review minor and major releases manually.

Document your configuration

Keep a changelog of:

Environment variables and their values
Custom configurations
Integration endpoints
SSL certificates and expiry dates
Signing certificate details

This makes rollbacks and troubleshooting much easier.

Updating Environment Variables

Some updates introduce new environment variables:

Check release notes for new variables
Review .env.example in the new version
Add new variables to your .env file
Restart the application for changes to take effect

Example when updating from 2.6 to 2.7:

# Compare your .env with the new .env.example
diff .env /path/to/documenso/.env.example

# Add any new required variables
echo "GOOGLE_VERTEX_PROJECT_ID=\"\"" >> .env
echo "GOOGLE_VERTEX_API_KEY=\"\"" >> .env

# Restart
docker compose restart documenso

Troubleshooting Updates

Common issues and solutions:

Container won't start after update

Symptom: Container exits immediately or enters a restart loopSolutions:

# Check logs for specific error
docker compose logs documenso

# Common causes:
# 1. Migration failure - check database logs
# 2. Missing environment variable - compare with .env.example
# 3. File permission issue - check volume mounts
# 4. Port conflict - ensure port 3000 is available

Migration timeout on large databases

Symptom: Migration fails with timeout errorSolutions:

# Increase statement timeout in PostgreSQL
docker exec -it documenso-db psql -U documenso -c \
  "ALTER DATABASE documenso SET statement_timeout = '600000';"

# Or set in postgresql.conf:
statement_timeout = 600000  # 10 minutes

# Retry the migration
docker compose restart documenso

Certificate signing stopped working

Symptom: Documents can’t be signed after updateSolutions:

# Check certificate status
curl http://localhost:3000/api/health

# Verify certificate file exists and is readable
docker exec documenso ls -la /opt/documenso/cert.p12

# Check environment variables
docker exec documenso env | grep SIGNING

# Ensure NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH points to correct location
# Default: /opt/documenso/cert.p12 (inside container)

For more issues, see the Troubleshooting guide.

Backups

Learn how to backup and restore your Documenso data

Monitoring

Set up monitoring and health checks

Troubleshooting

Common issues and their solutions

GitHub Releases

View all available versions and release notes

​Overview

​Version Information

​Pre-Update Checklist

​Docker Updates

​Using Docker Compose

​Using Docker Run

​Pinning to Specific Versions

​Manual/Bare-Metal Updates

​Kubernetes Updates

​Rollback in Kubernetes

​Database Migrations

​How Migrations Work

​Manual Migration Commands

​Migration Failures

​Post-Update Verification

​Health Checks

​Functional Tests

​Check Logs for Errors

​Rollback Procedures

​Docker Rollback

​Manual Rollback

​Update Best Practices

​Updating Environment Variables

​Troubleshooting Updates

​Related Resources

Backups

Monitoring

Troubleshooting

GitHub Releases

Overview

Version Information

Pre-Update Checklist

Docker Updates

Using Docker Compose

Using Docker Run

Pinning to Specific Versions

Manual/Bare-Metal Updates

Kubernetes Updates

Rollback in Kubernetes

Database Migrations

How Migrations Work

Manual Migration Commands

Migration Failures

Post-Update Verification

Health Checks

Functional Tests

Check Logs for Errors

Rollback Procedures

Docker Rollback

Manual Rollback

Update Best Practices

Updating Environment Variables

Troubleshooting Updates

Related Resources