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

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

## Version Policy

Documenso follows [Semantic Versioning](https://semver.org/):

| 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                |

<Callout type="info">
  Review the [release notes](https://github.com/documenso/documenso/releases) before upgrading to
  understand what changes are included.
</Callout>

### 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:

<Tabs items={['Docker', 'Docker Compose', 'Kubernetes']}>
<Tab value="Docker">

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

</Tab>
<Tab value="Docker Compose">

```bash
docker compose images
```

</Tab>
<Tab value="Kubernetes">

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

</Tab>
</Tabs>

### Check for New Releases

View available releases on GitHub:

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

Or visit the [releases page](https://github.com/documenso/documenso/releases).

### Check Available Docker Tags

List available image tags:

<Tabs items={['DockerHub', 'GitHub Container Registry']}>
<Tab value="DockerHub">

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

</Tab>
<Tab value="GitHub Container Registry">

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

</Tab>
</Tabs>

## Backup Before Upgrading

<Callout type="error">
  Always back up your database before upgrading. Upgrades may include database migrations that
  cannot be reversed.
</Callout>

### Database Backup

<Tabs items={['Docker Compose', 'Kubernetes', 'External Database']}>
<Tab value="Docker Compose">

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

</Tab>
<Tab value="Kubernetes">

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

</Tab>
<Tab value="External Database">

Use your database provider's backup tools or `pg_dump`:

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

</Tab>
</Tabs>

### Configuration Backup

Back up your environment configuration:

<Tabs items={['Docker / env file', 'Kubernetes']}>
<Tab value="Docker / env file">

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

</Tab>
<Tab value="Kubernetes">

Export your secrets and configmaps:

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

</Tab>
</Tabs>

See [Backups](/docs/self-hosting/maintenance/backups) for automated backup strategies.

## Upgrade Process

### Docker

{/* prettier-ignore */}
<Steps>
<Step>
### Pull the new image

```bash
docker pull documenso/documenso:<version>
```

Replace `<version>` with your target version.

</Step>
<Step>
### Stop the current container

```bash
docker stop documenso
docker rm documenso
```

</Step>
<Step>
### Start with the new image

```bash
docker run -d \
  --name documenso \
  -p 3000:3000 \
  --env-file .env \
  -v /path/to/cert.p12:/opt/documenso/cert.p12:ro \
  documenso/documenso:<version>
```

</Step>
<Step>
### Verify the upgrade

```bash
docker logs -f documenso
```

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

Test the health endpoint:

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

</Step>
</Steps>

### Docker Compose

{/* prettier-ignore */}
<Steps>
<Step>
### Update the image tag

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

```yaml
services:
  documenso:
    image: documenso/documenso:<version>
```

Or if using environment variable substitution:

```bash
# In .env
DOCUMENSO_VERSION=<version>
```

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

</Step>
<Step>
### Pull the new image

```bash
docker compose pull
```

</Step>
<Step>
### Apply the update

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

Docker Compose recreates containers that have changed images.

</Step>
<Step>
### Verify the upgrade

```bash
docker compose ps
docker compose logs -f documenso
```

Confirm the container is running and healthy.

</Step>
</Steps>

### Kubernetes

{/* prettier-ignore */}
<Steps>
<Step>
### Update the deployment image

Edit the deployment directly:

```bash
kubectl set image deployment/documenso \
  documenso=documenso/documenso:<version> \
  -n documenso
```

Or update your manifest file:

```yaml
spec:
  template:
    spec:
      containers:
        - name: documenso
          image: documenso/documenso:<version>
```

Then apply:

```bash
kubectl apply -f deployment.yaml
```

</Step>
<Step>
### Monitor the rollout

```bash
kubectl rollout status deployment/documenso -n documenso
```

Watch pods transition:

```bash
kubectl get pods -n documenso -w
```

</Step>
<Step>
### Verify the upgrade

Check the new pods are running:

```bash
kubectl get pods -n documenso -o wide
```

Test the health endpoint:

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

</Step>
</Steps>

## Database Migrations

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

### Migration Process

{/* prettier-ignore */}
<Steps>
<Step>
### Container starts

The container starts and connects to the database.

</Step>
<Step>
### Prisma checks for migrations

Prisma checks for pending migrations.

</Step>
<Step>
### Migrations run

Migrations are applied in order.

</Step>
<Step>
### Application starts

The application starts after migrations complete.

</Step>
</Steps>

### Checking Migration Status

View migration logs:

<Tabs items={['Docker / Docker Compose', 'Kubernetes']}>
<Tab value="Docker / Docker Compose">

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

</Tab>
<Tab value="Kubernetes">

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

</Tab>
</Tabs>

### 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:

{/* prettier-ignore */}
<Steps>
<Step>
### Adjust startup probe

Increase `failureThreshold` on the startup probe.

</Step>
<Step>
### Run migrations separately (optional)

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

</Step>
</Steps>

### Manual Migration (Advanced)

To run migrations manually before upgrading:

```bash
# Pull the new image
docker pull documenso/documenso:<version>

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

<Callout type="warn">
  This is an advanced operation. In most cases, automatic migrations are sufficient.
</Callout>

## Breaking Changes

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

### Before a Major Upgrade

{/* prettier-ignore */}
<Steps>
<Step>
### Read release notes

Read the [release notes](https://github.com/documenso/documenso/releases) carefully.

</Step>
<Step>
### Check environment variables

Check for required environment variable changes.

</Step>
<Step>
### Review configuration

Review any configuration deprecations.

</Step>
<Step>
### Back up database

Back up your database.

</Step>
<Step>
### Plan for downtime

Plan for potential downtime.

</Step>
</Steps>

### 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:

```bash
# 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

<Tabs items={['Docker', 'Docker Compose', 'Kubernetes']}>
<Tab value="Docker">

```bash
# 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:<previous-version>
```

</Tab>
<Tab value="Docker Compose">

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

</Tab>
<Tab value="Kubernetes">

```bash
# 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
```

</Tab>
</Tabs>

### Database Rollback

<Callout type="error">
  Database migrations cannot be automatically reversed. If you need to rollback after migrations
  have run, restore from your backup.
</Callout>

Restore from backup:

<Tabs items={['Docker Compose', 'External Database']}>
<Tab value="Docker Compose">

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

</Tab>
<Tab value="External Database">

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

</Tab>
</Tabs>

## Troubleshooting Upgrades

<Accordions type="multiple">
  <Accordion title="Container fails to start after upgrade">
    **Check logs:** `docker logs documenso`

    **Common causes:**
    - Missing env variable: check release notes for new required variables
    - Database connection error: verify database is accessible and credentials are valid
    - Migration failure: check logs for the specific migration error
    - Certificate error: verify certificate mount and passphrase

  </Accordion>
  <Accordion title="Migration errors">
    **What to do:**
    - Check the specific error in the logs
    - Verify database connectivity
    - Ensure the database user has `ALTER` permissions
    - Check for sufficient disk space on the database server

    **Test connectivity:**

    ```bash
    docker run --rm postgres:15 psql "postgresql://user:password@host:5432/documenso" -c "SELECT 1"
    ```

  </Accordion>
  <Accordion title="Application errors after upgrade">
    **If the application starts but behaves unexpectedly:**
    - Clear browser cache and cookies
    - Check for new environment variables in release notes
    - Verify all environment variables are correctly set
    - Check application logs: 
    
    ```bash
    docker logs documenso 2>&1 | grep -i -E "(warn|error)"
    ```
  </Accordion>
  <Accordion title="Performance issues after upgrade">
    **If performance degrades:**
    - New indexes being created can cause temporary slowdown (normal)
    - Monitor database CPU and memory usage
    - Review release notes for known performance impacts
    - Allow time for database query plans to stabilize
  </Accordion>
  <Accordion title="Rollback failed">
    **If rollback also fails:**
    - Verify the old image tag exists and is accessible
    - Check that your backup is valid and complete
    - Review environment configuration for any changes
    - Consider restoring to a clean database from backup
  </Accordion>
</Accordions>

## Upgrade Checklist

Use this checklist for each upgrade:

- [ ] Review release notes for the target version
- [ ] Check for breaking changes or new requirements
- [ ] Back up the database
- [ ] Back up environment configuration
- [ ] Note the current image tag for potential rollback
- [ ] Pull the new image
- [ ] Apply the upgrade
- [ ] Verify container starts successfully
- [ ] Check logs for migration completion
- [ ] Test the health endpoint
- [ ] Verify core functionality (login, document upload, signing)
- [ ] Monitor for errors in logs

---

## See Also

- [Backups](/docs/self-hosting/maintenance/backups) - Automated backup strategies
- [Troubleshooting](/docs/self-hosting/maintenance/troubleshooting) - Common issues and solutions
- [Environment Variables](/docs/self-hosting/configuration/environment) - Configuration reference