Deployment Rollbacks

Dokploy’s rollback feature allows you to instantly revert your application to any previous deployment version, minimizing downtime when issues occur in production.

How Rollbacks Work

Dokploy creates a versioned snapshot of each successful deployment, including:

Docker image with tag v{version}
Full application configuration
Environment variables
Build settings
Resource limits
Mounted volumes
Port configurations

Rollbacks restore the application state but do not revert database changes or external service modifications.

Enabling Rollbacks

Open Application Settings

Navigate to your application in Dokploy.

Enable Rollback Feature

Go to Settings and toggle “Rollback Active”:

Rollback Active: true ✅

Optional: Configure Registry

For persistent rollback storage, configure a rollback registry:

Docker Hub: Store rollback images in Docker Hub
GitHub Container Registry: Use GHCR for image storage
Custom Registry: Any Docker-compatible registry

Without a registry, rollback images are stored locally on the server.

Rollback Process

When rollbacks are enabled, each deployment:

Build Complete

Application builds successfully and image is created.

Version Tagged

Image is tagged with incremental version:

myapp:v1
myapp:v2
myapp:v3

Configuration Snapshot

Full application context is saved:

{
  "version": 3,
  "image": "myapp:v3",
  "env": "NODE_ENV=production\nPORT=3000",
  "buildArgs": "BUILD_DATE=2024-01-15",
  "memoryLimit": "512m",
  "cpuLimit": "0.5",
  "ports": [...],
  "mounts": [...]
}

Registry Push (Optional)

If rollback registry is configured:

docker tag myapp:v3 registry.example.com/myapp:v3
docker push registry.example.com/myapp:v3

Performing a Rollback

Via UI

Open Deployments

Navigate to the “Deployments” tab in your application.

View Deployment History

See list of all deployments with rollback points:

v5 - 2 hours ago (Current) ✅
v4 - 1 day ago 🔄
v3 - 2 days ago 🔄
v2 - 3 days ago 🔄
v1 - 1 week ago 🔄

Select Version

Click the rollback icon next to the version you want to restore.

Confirm Rollback

Review the rollback details and confirm:

Rollback from: v5 → v3
Configuration: Restored
Image: myapp:v3
Downtime: ~10-30 seconds

Automatic Deployment

Dokploy immediately:

Pulls the rollback image (or uses local)
Updates service configuration
Performs rolling update
Verifies health checks

Via API

curl -X POST https://dokploy.example.com/api/rollback \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "rollbackId": "rollback_abc123"
  }'

What Gets Rolled Back

Included
Not Included

✅ Rolled back to previous state:

Application code (Docker image)
Environment variables
Build arguments and secrets
CPU and memory limits
Custom commands
Port mappings
Volume mount configurations
Network settings
Health check settings
Replica count

Rollback Registry

Configure a registry to store rollback images for long-term retention:

Docker Hub
GitHub Container Registry
Custom Registry
Local Only

Registry Type: Docker Hub
Username: myusername
Password: <token>

Images are pushed as:

docker.io/myusername/myapp:v1
docker.io/myusername/myapp:v2

Registry Type: Custom
Registry URL: ghcr.io
Username: myusername
Password: <github-token>
Image Prefix: ghcr.io/myorg

Images are pushed as:

ghcr.io/myorg/myapp:v1
ghcr.io/myorg/myapp:v2

Registry Type: Custom
Registry URL: registry.example.com
Username: admin
Password: <password>
Image Prefix: registry.example.com/apps

Images are pushed as:

registry.example.com/apps/myapp:v1
registry.example.com/apps/myapp:v2

No registry configured:

Rollback Registry: None

Images stored only on the server:

myapp:v1 (local)
myapp:v2 (local)

Local-only rollbacks are lost if the server is destroyed or rebuilt.

Managing Rollback Points

Viewing Rollback History

Each deployment shows:

┌─────────────────────────────────────────────────┐
│ Version 5 (Current)                              │
│ Deployed: 2 hours ago                            │
│ Image: myapp:v5                                  │
│ Status: Running ✅                               │
│ Actions: [View Logs] [Rollback Available: v4]   │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ Version 4                                        │
│ Deployed: 1 day ago                              │
│ Image: myapp:v4                                  │
│ Rollback: [Restore to v4] [Delete]              │
└─────────────────────────────────────────────────┘

Deleting Rollback Points

Remove old rollback versions to free up storage:

Open Deployments

View deployment history in your application.

Delete Rollback

Click delete icon next to the rollback version.

Confirm Deletion

Dokploy removes:

- Docker image (myapp:v3)
- Configuration snapshot
- Registry image (if configured)

Deleted rollback points cannot be recovered. Keep at least 2-3 recent versions.

Zero-Downtime Rollbacks

Dokploy performs rolling updates during rollbacks:

Pull Image

Download rollback image from registry or use local cache:

docker pull myapp:v3

Start New Container

Create container with rollback configuration:

docker service update \
  --image myapp:v3 \
  --update-parallelism 1 \
  --update-delay 10s \
  myapp

Health Check

Wait for new container to pass health checks:

HTTP GET /health → 200 OK ✅

Remove Old Container

Stop and remove the failed version:

docker service update complete
Old containers removed

Rolling updates ensure your application stays available during rollbacks.

Rollback Scenarios

Critical Bug Deployed

Situation: New deployment introduced a critical bug.Action:

Identify last known good version
Click rollback to that version
Application reverts in ~30 seconds
Fix bug in development
Deploy fixed version

Performance Degradation

Situation: New deployment causes performance issues.Action:

Monitor metrics and confirm regression
Rollback to previous version
Investigate performance issues locally
Optimize and redeploy

Failed Migration

Situation: Database migration fails mid-deployment.Action:

Rollback application code

Manually rollback database migration:

npm run migrate:rollback
rails db:rollback

Fix migration script
Test migration locally
Deploy with corrected migration

Dokploy rollbacks do NOT automatically revert database changes.

Configuration Error

Situation: Wrong environment variable deployed.Action:

Rollback to restore previous environment variables
Update environment variables in Dokploy
Redeploy or update service:
```
docker service update --force myapp
```

Best Practices

Use Rollback Registry

Configure external registry for persistence:

✅ Registry: ghcr.io
❌ Local only

Keep Recent Versions

Maintain 3-5 recent rollback points:

v5 (current)
v4 (1 day old)   ← keep
v3 (3 days old)  ← keep
v2 (1 week old)  ← keep
v1 (2 weeks old) → delete

Test Rollbacks

Periodically test rollback process:

Deploy to staging
Perform rollback
Verify functionality
Document process

Monitor After Rollback

Watch metrics post-rollback:

- Error rates
- Response times
- Resource usage
- User reports

Database Rollback Strategy

Since Dokploy doesn’t automatically rollback databases, implement a migration strategy:

Reversible Migrations
Backup Before Deploy
Blue-Green Databases

Write migrations that can be rolled back:

// migrations/001_add_users_table.js
exports.up = async (db) => {
  await db.schema.createTable('users', (table) => {
    table.increments('id');
    table.string('email');
  });
};

exports.down = async (db) => {
  await db.schema.dropTable('users');
};

Rollback command:

npm run migrate:down

Always backup before deploying:

# Before deployment
docker exec postgres pg_dump mydb > backup.sql

# If rollback needed
docker exec -i postgres psql mydb < backup.sql

Use separate databases for major versions:

Version 1: mydb_v1
Version 2: mydb_v2

Rollback: Switch connection to mydb_v1

Troubleshooting

Rollback Image Not Found

Error: Image myapp:v3 not found

Solutions:
1. Check if image exists locally:
   docker images | grep myapp

2. Check registry:
   docker pull registry.example.com/myapp:v3

3. If image was deleted:
   ❌ Cannot rollback to this version
   ✅ Choose different version

Rollback Fails to Start

Check Compatibility

Ensure rollback version is compatible:

# Check dependencies
- Database schema version
- External API versions
- Required services

Review Logs

Check container startup logs:

docker service logs myapp

Verify Configuration

Ensure rollback configuration is valid:

- Environment variables
- Volume mounts
- Network settings

Registry Push Failures

Error: Failed to push rollback image to registry

Solutions:
1. Verify credentials:
   docker login registry.example.com

2. Check network connectivity:
   ping registry.example.com

3. Verify permissions:
   - Registry write access
   - Storage quota

Rollback vs. Redeploy

Rollback
Redeploy

Use when: Recent deployment failedProcess:

Instant (uses existing image)
No build required
Restores exact previous state
~30 seconds downtime

Command:

Rollback to v3

Use when: Need to rebuild current versionProcess:

Rebuilds from source
Fresh dependencies
Creates new image
~2-10 minutes build time

Command:

Redeploy current version

Getting Started

Deployment

Databases

Infrastructure

Advanced

Deployment Rollbacks

How Rollbacks Work

Enabling Rollbacks

Rollback Process

Performing a Rollback

Via UI

Via API

What Gets Rolled Back

Rollback Registry

Managing Rollback Points

Viewing Rollback History

Deleting Rollback Points

Zero-Downtime Rollbacks

Rollback Scenarios

Best Practices

Use Rollback Registry

Keep Recent Versions

Test Rollbacks

Monitor After Rollback

Database Rollback Strategy

Troubleshooting

Rollback Image Not Found

Rollback Fails to Start

Registry Push Failures

Rollback vs. Redeploy

Next Steps

Preview Deployments

Environment Variables

Getting Started

Deployment

Databases

Infrastructure

Advanced

Documentation Index

​How Rollbacks Work

​Enabling Rollbacks

​Rollback Process

​Performing a Rollback

​Via UI

​Via API

​What Gets Rolled Back

​Rollback Registry

​Managing Rollback Points

​Viewing Rollback History

​Deleting Rollback Points

​Zero-Downtime Rollbacks

​Rollback Scenarios

​Best Practices

Use Rollback Registry

Keep Recent Versions

Test Rollbacks

Monitor After Rollback

​Database Rollback Strategy

​Troubleshooting

​Rollback Image Not Found

​Rollback Fails to Start

​Registry Push Failures

​Rollback vs. Redeploy

​Next Steps

Preview Deployments

Environment Variables

How Rollbacks Work

Enabling Rollbacks

Rollback Process

Performing a Rollback

Via UI

Via API

What Gets Rolled Back

Rollback Registry

Managing Rollback Points

Viewing Rollback History

Deleting Rollback Points

Zero-Downtime Rollbacks

Rollback Scenarios

Best Practices

Database Rollback Strategy

Troubleshooting

Rollback Image Not Found

Rollback Fails to Start

Registry Push Failures

Rollback vs. Redeploy

Next Steps