mirror of
https://github.com/documenso/documenso.git
synced 2026-07-13 06:25:01 +10:00
Lucas Smith
652 lines
14 KiB
Plaintext
652 lines
14 KiB
Plaintext
---
|
|
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:1.6.0
|
|
```
|
|
|
|
Replace `1.6.0` 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:1.6.0
|
|
```
|
|
|
|
</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:1.6.0
|
|
```
|
|
|
|
Or if using environment variable substitution:
|
|
|
|
```bash
|
|
# In .env
|
|
DOCUMENSO_VERSION=1.6.0
|
|
```
|
|
|
|
```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:1.6.0 \
|
|
-n documenso
|
|
```
|
|
|
|
Or update your manifest file:
|
|
|
|
```yaml
|
|
spec:
|
|
template:
|
|
spec:
|
|
containers:
|
|
- name: documenso
|
|
image: documenso/documenso:1.6.0
|
|
```
|
|
|
|
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: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
|
|
```
|
|
|
|
<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:1.5.0
|
|
```
|
|
|
|
</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
|