From 011359836c6683de7ab860e902d80801b8b5acb6 Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Sun, 7 Dec 2025 19:18:39 -0600 Subject: [PATCH] docs: expand rollbacks documentation with detailed mechanisms and configurations - Added sections on Docker Swarm and registry-based rollback mechanisms, explaining their functionalities and differences. - Included prerequisites and steps for enabling registry-based rollbacks, enhancing user control over application versions. - Improved clarity with callouts emphasizing important considerations for both rollback methods. - Updated the structure to provide a comprehensive guide for users on managing application rollbacks effectively. --- .../docs/core/applications/rollbacks.mdx | 76 +++++++++++++++---- 1 file changed, 61 insertions(+), 15 deletions(-) diff --git a/apps/docs/content/docs/core/applications/rollbacks.mdx b/apps/docs/content/docs/core/applications/rollbacks.mdx index dfb15ec..bb70a24 100644 --- a/apps/docs/content/docs/core/applications/rollbacks.mdx +++ b/apps/docs/content/docs/core/applications/rollbacks.mdx @@ -3,16 +3,35 @@ title: Rollbacks description: Learn how to rollback your application in Dokploy. --- +import { Callout } from 'fumadocs-ui/components/callout'; + Rollbacks are a powerful feature that allows you to easily revert changes to your application. This is particularly useful when you encounter issues or want to revert to a previous version of your application. +## Types of Rollbacks + +Dokploy supports two types of rollback mechanisms: + +1. **Docker Swarm Rollbacks** (Automatic): Based on health checks, automatically reverts to the previous version if a deployment fails health checks +2. **Registry-based Rollbacks** (Manual): Uses Docker registry to store each deployment's image, allowing you to manually rollback to any specific deployment version + + + The rollback methods described in the first section of this guide are based on **Docker Swarm's automatic rollback feature**. Dokploy also supports **registry-based rollbacks** at the deployment level, which allows you to save each deployment's image to a registry and rollback to any specific version. See the "Rollback to a specific version" section below for more details. + ## Requirements 1. Have a `/health` endpoint in your application. 2. Have `curl` available in your container (if you use alpine for example, it won't be installed by default). -## Steps to Rollback +## Docker Swarm Automatic Rollback +This method uses Docker Swarm's built-in rollback feature, which automatically reverts to the previous version if health checks fail during deployment. + + + This rollback method is **automatic** and based on Docker Swarm's health check system. It only works if the new deployment fails health checks, triggering an automatic rollback to the previous version. + + +### Steps to Configure Automatic Rollback Let's suppose we have a NodeJS application that has a health check route `/api/health` that returns a 200 status code and running in the port 3000. @@ -50,25 +69,55 @@ Paste the following code: } ``` -## Rollback to a specific version +## Registry-based Rollback to Specific Versions -The previous steps covered Docker Swarm's automatic rollback feature. Since v0.23.0, Dokploy also supports manual rollbacks to specific deployment points, giving you more control over your application versions. +The previous section covered Docker Swarm's automatic rollback feature, which only works when health checks fail. Dokploy also supports **registry-based rollbacks** at the deployment level, which provides more control and flexibility. -### Enabling Rollback Feature +### How Registry-based Rollbacks Work -To start saving deployment snapshots for rollbacks: +When using registry-based rollbacks, Dokploy: + +- **Saves each deployment's image to your configured registry**: Every time you deploy, the built image is tagged and pushed to your Docker registry (Docker Hub, GHCR, etc.) +- **Associates each deployment with its image**: Each deployment record in Dokploy is linked to a specific image tag in your registry +- **Enables rollback to any deployment**: You can rollback to any previous deployment by using the image that was saved during that deployment + +This approach is different from Docker Swarm rollbacks because: +- ✅ **Works with any deployment**: Not limited to health check failures +- ✅ **Rollback to any version**: Can rollback to any previous deployment, not just the immediate previous one +- ✅ **Uses registry storage**: Images are stored in your registry, making them persistent and accessible + + + Registry-based rollbacks require that your application is configured to use a Docker registry. The images are automatically pushed to your registry during each deployment, and Dokploy tracks which image corresponds to each deployment. + + +### Prerequisites for Registry-based Rollbacks + +To use registry-based rollbacks, you need: + +1. **A configured Docker registry** in Dokploy (Docker Hub, GHCR, or custom registry) +2. **Registry credentials** set up in Dokploy's registry settings +3. **Application configured to push images** to the registry during deployment + + + When you enable rollbacks, Dokploy will automatically push each deployment's image to your configured registry with a unique tag, allowing you to rollback to any specific deployment version. + + +### Enabling Registry-based Rollbacks + +To start saving deployment images to your registry for rollbacks: 1. Navigate to your application 2. Go to **Deployments** → **Rollback Settings** 3. Enable the **Rollback** option +4. Select the registry you want to use for rollbacks +5. Click on **Save** -### How it works +Once enabled, Dokploy will: +- **Automatically tag and push images**: Every deployment's image is tagged and pushed to your configured registry +- **Track deployment associations**: Each deployment is linked to its specific image tag in the registry +- **Enable rollback buttons**: You'll see a **Rollback** button next to each deployment in the Deployments section -- **Automatic snapshots**: Every time you deploy, Dokploy creates a rollback point associated with that deployment -- **Manual rollback**: Click the **Rollback** button next to any deployment to revert to that specific version -- **Automatic cleanup**: When old deployments are deleted, their associated rollback snapshots and images are also removed to save space - -### Performing a rollback +### Performing a Registry-based Rollback 1. Go to your application's **Deployments** section 2. Find the deployment version you want to rollback to @@ -76,9 +125,6 @@ To start saving deployment snapshots for rollbacks: 4. Confirm the rollback action - Having rollbacks enabled will increase storage usage, as it saves previous versions of your application. Consider your storage capacity when enabling this feature. + After clicking **Rollback**, you'll need to wait a few seconds for Dokploy to download the image from your registry. The container will not appear in the **Logs** tab immediately - wait a moment for the image download to complete before checking the logs to see the container running. - - **Important**: If you manually clean Docker images using commands like `docker image prune` or `docker system prune`, the rollback snapshots may be lost. Avoid cleaning Docker images if you want to preserve your rollback history. -