Upgrades

Upgrade your self-hosted Documenso installation to get the latest features, security patches, and bug fixes.

Version Policy

Version Type	Format	Description
Major	`x.0.0`	Breaking changes, may require manual steps
Minor	`x.y.0`	New features, backward compatible
Patch	`x.y.z`	Bug fixes, security patches

Review the release notes before upgrading to understand what changes are included.

Image Tags

Tag	Description	Use Case
`latest`	Most recent stable release	Development, testing
`x.y.z`	Specific version (e.g., `1.5.0`)	Production
`release`	Latest build from release branch	Pre-release testing

For production deployments, pin to a specific version tag to avoid unexpected updates.

Checking for Updates

View Current Version

Check your running Documenso version:

docker inspect documenso --format='{{.Config.Image}}'

docker compose images

kubectl get deployment documenso -n documenso -o jsonpath='{.spec.template.spec.containers[0].image}'

Check for New Releases

View available releases on GitHub:

curl -s https://api.github.com/repos/documenso/documenso/releases/latest | grep tag_name

Or visit the releases page.

Check Available Docker Tags

List available image tags:

curl -s https://hub.docker.com/v2/repositories/documenso/documenso/tags | jq -r '.results[].name'

curl -s https://api.github.com/orgs/documenso/packages/container/documenso/versions | jq -r '.[].metadata.container.tags[]'

Backup Before Upgrading

Always back up your database before upgrading. Upgrades may include database migrations that cannot be reversed.

Database Backup

docker compose exec database pg_dump -U documenso documenso > backup-$(date +%Y%m%d-%H%M%S).sql

kubectl exec -n documenso deploy/postgres -- pg_dump -U documenso documenso > backup-$(date +%Y%m%d-%H%M%S).sql

Use your database provider's backup tools or pg_dump:

pg_dump "postgresql://user:password@host:5432/documenso" > backup-$(date +%Y%m%d-%H%M%S).sql

Configuration Backup

Back up your environment configuration:

cp .env .env.backup-$(date +%Y%m%d)

Export your secrets and configmaps:

kubectl get secret documenso-secrets -n documenso -o yaml > secrets-backup.yaml
kubectl get configmap documenso-config -n documenso -o yaml > configmap-backup.yaml

See Backups for automated backup strategies.

Upgrade Process

Docker

Pull the new image

docker pull documenso/documenso:1.6.0

Replace 1.6.0 with your target version.

Stop the current container

docker stop documenso
docker rm documenso

Start with the new image

docker run -d \
  --name documenso \
  -p 3000:3000 \
  --env-file .env \
  -v /path/to/cert.p12:/opt/documenso/cert.p12:ro \
  documenso/documenso:1.6.0

Verify the upgrade

docker logs -f documenso

Wait for "Ready" or "Listening on port 3000" in the output.

Test the health endpoint:

curl http://localhost:3000/api/health

Docker Compose

Update the image tag

Edit compose.yml or your .env file to specify the new version:

services:
  documenso:
    image: documenso/documenso:1.6.0

Or if using environment variable substitution:

# In .env
DOCUMENSO_VERSION=1.6.0

# In compose.yml
services:
  documenso:
    image: documenso/documenso:${DOCUMENSO_VERSION:-latest}

Pull the new image

docker compose pull

Apply the update

docker compose --env-file .env up -d

Docker Compose recreates containers that have changed images.

Verify the upgrade

docker compose ps
docker compose logs -f documenso

Confirm the container is running and healthy.

Kubernetes

Update the deployment image

Edit the deployment directly:

kubectl set image deployment/documenso \
  documenso=documenso/documenso:1.6.0 \
  -n documenso

Or update your manifest file:

spec:
  template:
    spec:
      containers:
        - name: documenso
          image: documenso/documenso:1.6.0

Then apply:

kubectl apply -f deployment.yaml

Monitor the rollout

kubectl rollout status deployment/documenso -n documenso

Watch pods transition:

kubectl get pods -n documenso -w

Verify the upgrade

Check the new pods are running:

kubectl get pods -n documenso -o wide

Test the health endpoint:

kubectl port-forward svc/documenso 3000:80 -n documenso &
curl http://localhost:3000/api/health

Database Migrations

Documenso runs database migrations automatically when the container starts. No manual intervention is required.

Migration Process

Container starts

The container starts and connects to the database.

Prisma checks for migrations

Prisma checks for pending migrations.

Migrations run

Migrations are applied in order.

Application starts

The application starts after migrations complete.

Checking Migration Status

View migration logs:

docker logs documenso 2>&1 | grep -i migration

kubectl logs -l app.kubernetes.io/name=documenso -n documenso | grep -i migration

Slow Migrations

Large databases may take longer to migrate. The startup probe in Kubernetes allows up to 150 seconds (30 failures x 5 second period) for migrations to complete.

If migrations take longer:

Adjust startup probe

Increase failureThreshold on the startup probe.

Run migrations separately (optional)

Consider running migrations manually before upgrading (see Manual Migration below).

Manual Migration (Advanced)

To run migrations manually before upgrading:

# Pull the new image
docker pull documenso/documenso:1.6.0

# Run migrations only
docker run --rm \
  -e NEXT_PRIVATE_DATABASE_URL="postgresql://user:password@host:5432/documenso" \
  documenso/documenso:1.6.0 \
  npx prisma migrate deploy

This is an advanced operation. In most cases, automatic migrations are sufficient.

Breaking Changes

Major version upgrades may include breaking changes that require manual steps.

Before a Major Upgrade

Read release notes

Read the release notes carefully.

Check environment variables

Check for required environment variable changes.

Review configuration

Review any configuration deprecations.

Back up database

Back up your database.

Plan for downtime

Plan for potential downtime.

Common Breaking Changes

Change Type	Action Required
New required env variable	Add the variable to your configuration
Removed env variable	Remove from configuration to avoid confusion
Renamed env variable	Update to the new name
Database schema change	Automatic migration (back up first)
API changes	Update integrations using the API

Environment Variable Changes

Compare your current environment with the latest example:

# Download latest example
curl -O https://raw.githubusercontent.com/documenso/documenso/main/.env.example

# Compare with your current config
diff .env .env.example

Rollback Procedure

If an upgrade fails, roll back to the previous version.

Container Rollback

# Stop the new container
docker stop documenso
docker rm documenso

# Start with the previous image
docker run -d \
  --name documenso \
  -p 3000:3000 \
  --env-file .env \
  -v /path/to/cert.p12:/opt/documenso/cert.p12:ro \
  documenso/documenso:1.5.0

# Revert the image tag in compose.yml or .env
# Then recreate containers
docker compose --env-file .env up -d

# View rollout history
kubectl rollout history deployment/documenso -n documenso

# Rollback to previous version
kubectl rollout undo deployment/documenso -n documenso

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

Database Rollback

Database migrations cannot be automatically reversed. If you need to rollback after migrations have run, restore from your backup.

Restore from backup:

docker compose exec -T database psql -U documenso documenso < backup-20240115-120000.sql

psql "postgresql://user:password@host:5432/documenso" < backup-20240115-120000.sql

Troubleshooting Upgrades

Upgrade Checklist

Use this checklist for each upgrade:

Container fails to start after upgrade

Migration errors

Application errors after upgrade

Performance issues after upgrade

Rollback failed

On this page