From af2ce6037acfb3ac75b7ac27f22966101afcaa44 Mon Sep 17 00:00:00 2001 From: Tam Nguyen Date: Wed, 5 Feb 2025 13:40:05 +1100 Subject: [PATCH 1/9] fix: use 127.0.0.1 instead of localhost due to IPv6 --- .../docs/content/docs/core/applications/going-production.mdx | 2 +- apps/docs/content/docs/core/applications/rollbacks.mdx | 2 +- apps/docs/content/docs/core/applications/zero-downtime.mdx | 5 ++--- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/apps/docs/content/docs/core/applications/going-production.mdx b/apps/docs/content/docs/core/applications/going-production.mdx index d64ade35..679e8efe 100644 --- a/apps/docs/content/docs/core/applications/going-production.mdx +++ b/apps/docs/content/docs/core/applications/going-production.mdx @@ -184,7 +184,7 @@ Make sure the API Route exists in your application "CMD", "curl", "-f", - "http://localhost:3000/health" + "http://127.0.0.1:3000/health" ], "Interval": 30000000000, "Timeout": 10000000000, diff --git a/apps/docs/content/docs/core/applications/rollbacks.mdx b/apps/docs/content/docs/core/applications/rollbacks.mdx index e47a156e..26041dbc 100644 --- a/apps/docs/content/docs/core/applications/rollbacks.mdx +++ b/apps/docs/content/docs/core/applications/rollbacks.mdx @@ -27,7 +27,7 @@ Make sure the API Route exists in your application "CMD", "curl", "-f", - "http://localhost:3000/api/health" + "http://127.0.0.1:3000/api/health" ], "Interval": 30000000000, "Timeout": 10000000000, diff --git a/apps/docs/content/docs/core/applications/zero-downtime.mdx b/apps/docs/content/docs/core/applications/zero-downtime.mdx index ddab2c99..f6de9c57 100644 --- a/apps/docs/content/docs/core/applications/zero-downtime.mdx +++ b/apps/docs/content/docs/core/applications/zero-downtime.mdx @@ -26,7 +26,7 @@ Make sure the API Route exists in your application "CMD", "curl", "-f", - "http://localhost:3000/api/health" + "http://127.0.0.1:3000/api/health" ], "Interval": 30000000000, "Timeout": 10000000000, @@ -70,7 +70,6 @@ We will use this configuration specifically, paste and save it This configuration basically tells to Docker to do: -Make a request inside the container to http://localhost:3000/health and then we are also saying to make in interval of 30000000000 nanosec, and also makes 3 retries before switching to the new container +Make a request inside the container to http://127.0.0.1:3000/health and then we are also saying to make in interval of 30000000000 nanosec, and also makes 3 retries before switching to the new container that would be all, Now you have Zero Downtime Deployments 🎊. - From 2370a9dab3c12acb9e43c4418c03f8351551177a Mon Sep 17 00:00:00 2001 From: Tam Nguyen Date: Wed, 5 Feb 2025 14:03:40 +1100 Subject: [PATCH 2/9] docs: improved documentation wording for zero-downtime --- .../docs/core/applications/zero-downtime.mdx | 97 +++++++++++-------- 1 file changed, 58 insertions(+), 39 deletions(-) diff --git a/apps/docs/content/docs/core/applications/zero-downtime.mdx b/apps/docs/content/docs/core/applications/zero-downtime.mdx index f6de9c57..f13e5080 100644 --- a/apps/docs/content/docs/core/applications/zero-downtime.mdx +++ b/apps/docs/content/docs/core/applications/zero-downtime.mdx @@ -3,55 +3,69 @@ title: Zero Downtime description: Learn how to configure zero downtime deployments in Dokploy. --- +By default, when you create a new deployment, it will stop the latest running container and start the new one. This is the default behavior of Docker Swarm and this leads to Bad Gateway since +the containers are initialized at the same time. -Dokploy allows you to configure zero downtime deployments, which means that you can deploy your application without any downtime. - -By default when you create a new deployment it will stop the latest running container and start the new one. This is the default behavior of Docker Swarm and this leads to Bad Gateway since -the containers are initializing at the same time, -but Dokploy allows you to configure zero downtime deployments. +Dokploy allows you to configure zero downtime deployments, which means that you can deploy your application without any disruption. ## Steps to configure Zero Downtime Deployments -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. - -1. In your application is necessary to have a `Path` or `Health Route` to be able to achieve zero downtime deployments eg. in the case of a NodeJS app you can have a route `/api/health` that returns a 200 status code. -2. Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings` -3. There are a couple options that you can use, in this case we will focus on `Health Check`. -4. Paste this code in the health check field: -Make sure the API Route exists in your application - -```json -{ - "Test": [ - "CMD", - "curl", - "-f", - "http://127.0.0.1:3000/api/health" - ], - "Interval": 30000000000, - "Timeout": 10000000000, - "StartPeriod": 30000000000, - "Retries": 3 -} -``` +Suppose we have a NodeJS application running on port 3000 with a health check route `/api/health` that returns a 200 status code. +To enable zero-downtime, + +1. Go to the `Advanced` Tab, under Cluster Settings, and click the button `Swarm Settings` +2. Paste the code below in the `Health Check` field: + ```json + { + "Test": [ + "CMD", + "curl", + "-f", + "http://127.0.0.1:3000/api/health" + ], + "Interval": 30000000000, + "Timeout": 10000000000, + "StartPeriod": 30000000000, + "Retries": 3 + } + ``` + Note: + 1. Ensure the API Route exists in your application + 2. For Dockerfile deployments, ensure that + - your host is configured to listen to 127.0.0.1 (or 0.0.0.0) + - your docker image has `curl` installed - this is not available by default on alpine. Alternatively, you can use wget: + ```json + "Test": [ + "CMD", + "wget", + "--spider", + "-q", + "http://127.0.0.1:3000/api/health" + ], + ``` ## Example -1. We will use this example [Github Repo](https://github.com/Dokploy/swarm-test) -2. It Have a endpoint called `health` [endpoint](https://github.com/Dokploy/swarm-test/blob/main/index.js#L20) which is the one that will tell us if our application is healthy. -3. For testing purpose I've added a sleep to simulate the delay between the deployments and you can see the bad gateway error. - +- We will use this example [Github Repo](https://github.com/Dokploy/swarm-test) +- It has an endpoint called `/health` [endpoint](https://github.com/Dokploy/swarm-test/blob/main/index.js#L20) which will inform us if our application is healthy +- For testing purposes, I've invoked a sleep function to simulate delays. This will allow us to see the "Bad Gateway" error between deployments -1. **Use Git Provider in Your Application**: +**Use Git Provider in Your Application**: - Repository: `https://github.com/Dokploy/swarm-test` - Branch: `main` - Build path: `/` -If you want to test that there is no zero downtime yet, you can simply deploy the application and then create another deployment and while doing the deployment reload the page in the path /health and you will see that a bad gateway will appear. +To verify that zero downtime deployment is not yet enabled, follow these steps: +1. Deploy the application. +2. Initiate another deployment. +3. While the deployment is in progress, reload the /health page. +4. You should observe a Bad Gateway error, indicating downtime during the deployment process. -Now go to the advanced section of our application, and go to the Swarm Settings section, we are going to modify the first section of Healtchecks. - -We will use this configuration specifically, paste and save it +To configure health checks for zero downtime. +1. Go to the `Advanced` tab of the application. +2. Navigate to `Swarm Settings`. +3. Locate the `Health Checks` section. +4. Replace the existing configuration with the following: ```json { @@ -68,8 +82,13 @@ We will use this configuration specifically, paste and save it } ``` -This configuration basically tells to Docker to do: +This configuration instructs Docker to: + +1. Send a request inside the container to http://127.0.0.1:3000/health. +2. Perform health checks every 30 seconds (30,000,000,000 nanoseconds). +3. Wait up to 10 seconds (10,000,000,000 nanoseconds) for a response. +4. Allow the container 30 seconds (30,000,000,000 nanoseconds) to start before running checks. +5. Retry the health check 3 times before considering the container unhealthy. -Make a request inside the container to http://127.0.0.1:3000/health and then we are also saying to make in interval of 30000000000 nanosec, and also makes 3 retries before switching to the new container +With this setup, new deployments will only replace old containers after the new instance passes health checks, preventing downtime 🎊. -that would be all, Now you have Zero Downtime Deployments 🎊. From 3e387dbfa21ae8835987c71365b41f7084a61c18 Mon Sep 17 00:00:00 2001 From: Tam Nguyen Date: Wed, 5 Feb 2025 14:36:17 +1100 Subject: [PATCH 3/9] fix: apply the same changes to rollback --- .../docs/core/applications/rollbacks.mdx | 75 +++++++++++-------- .../docs/core/applications/zero-downtime.mdx | 4 +- 2 files changed, 44 insertions(+), 35 deletions(-) diff --git a/apps/docs/content/docs/core/applications/rollbacks.mdx b/apps/docs/content/docs/core/applications/rollbacks.mdx index 26041dbc..1caf1a2b 100644 --- a/apps/docs/content/docs/core/applications/rollbacks.mdx +++ b/apps/docs/content/docs/core/applications/rollbacks.mdx @@ -13,40 +13,49 @@ Rollbacks are a powerful feature that allows you to easily revert changes to you ## Steps to 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. +Suppose we have a NodeJS application running on port 3000 with a health check route `/api/health` that returns a 200 status code. 1. In your application is necessary to have a `Path` or `Health Route` to be able to achieve zero downtime deployments eg. in the case of a NodeJS app you can have a route `/api/health` that returns a 200 status code. 2. Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings` 3. There are a couple options that you can use, in this case we will focus on `Health Check` and `Update Config`. -4. Paste this code in the health check field: -Make sure the API Route exists in your application - -```json -{ - "Test": [ - "CMD", - "curl", - "-f", - "http://127.0.0.1:3000/api/health" - ], - "Interval": 30000000000, - "Timeout": 10000000000, - "StartPeriod": 30000000000, - "Retries": 3 -} -``` -5. Now in the `Update Config` - -Now when the application is getting unhealthy response from the health check, the container will rollback to the previous version. - -Paste the following code: -```json -{ - "Parallelism": 1, - "Delay": 10000000000, - "FailureAction": "rollback", - "Order": "start-first" -} -``` - - +4. Paste the code below in the `Health Check` field: + ```json + { + "Test": [ + "CMD", + "curl", + "-f", + "http://127.0.0.1:3000/api/health" + ], + "Interval": 30000000000, + "Timeout": 10000000000, + "StartPeriod": 30000000000, + "Retries": 3 + } + ``` + Note: + 1. Ensure the API Route exists in your application + 2. For Dockerfile deployments, ensure that + - your host is configured to listen to 127.0.0.1 (or 0.0.0.0). For example, for NextJS Dockerfile, ensure `ENV HOSTNAME=0.0.0.0` is set. + - your docker image has `curl` installed (this is not available by default on alpine-based images). Alternatively, you can use wget: + ```json + "Test": [ + "CMD", + "wget", + "--spider", + "-q", + "http://127.0.0.1:3000/api/health" + ], + ``` + +5. Next, in the `Update Config` field, copy and paste this code block: + ```json + { + "Parallelism": 1, + "Delay": 10000000000, + "FailureAction": "rollback", + "Order": "start-first" + } + ``` + +Now when the application is getting unhealthy response from the health check, the container will rollback to the previous version. \ No newline at end of file diff --git a/apps/docs/content/docs/core/applications/zero-downtime.mdx b/apps/docs/content/docs/core/applications/zero-downtime.mdx index f13e5080..cffad7ca 100644 --- a/apps/docs/content/docs/core/applications/zero-downtime.mdx +++ b/apps/docs/content/docs/core/applications/zero-downtime.mdx @@ -32,8 +32,8 @@ To enable zero-downtime, Note: 1. Ensure the API Route exists in your application 2. For Dockerfile deployments, ensure that - - your host is configured to listen to 127.0.0.1 (or 0.0.0.0) - - your docker image has `curl` installed - this is not available by default on alpine. Alternatively, you can use wget: + - your host is configured to listen to 127.0.0.1 (or 0.0.0.0). For example, for NextJS Dockerfile, ensure `ENV HOSTNAME=0.0.0.0` is set. + - your docker image has `curl` installed - this is not available by default on alpine-based images. Alternatively, you can use wget: ```json "Test": [ "CMD", From 5c4091e05c5a3a39349cf37cb76c69240410e034 Mon Sep 17 00:00:00 2001 From: Tam Nguyen Date: Wed, 5 Feb 2025 14:46:36 +1100 Subject: [PATCH 4/9] fix: simplify rollback docs by referencing zero downtime for healthchecks --- .../docs/core/applications/rollbacks.mdx | 46 ++++--------------- 1 file changed, 9 insertions(+), 37 deletions(-) diff --git a/apps/docs/content/docs/core/applications/rollbacks.mdx b/apps/docs/content/docs/core/applications/rollbacks.mdx index 1caf1a2b..42bf711d 100644 --- a/apps/docs/content/docs/core/applications/rollbacks.mdx +++ b/apps/docs/content/docs/core/applications/rollbacks.mdx @@ -3,52 +3,24 @@ title: Rollbacks description: Learn how to rollback your application in Dokploy. --- -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. +import Link from 'next/link'; +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. ## Requirements 1. Have a `/health` endpoint in your application. +2. Configured `Health Check` by following the instructions in the Zero Downtime Instructions ## Steps to Rollback - Suppose we have a NodeJS application running on port 3000 with a health check route `/api/health` that returns a 200 status code. -1. In your application is necessary to have a `Path` or `Health Route` to be able to achieve zero downtime deployments eg. in the case of a NodeJS app you can have a route `/api/health` that returns a 200 status code. -2. Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings` -3. There are a couple options that you can use, in this case we will focus on `Health Check` and `Update Config`. -4. Paste the code below in the `Health Check` field: - ```json - { - "Test": [ - "CMD", - "curl", - "-f", - "http://127.0.0.1:3000/api/health" - ], - "Interval": 30000000000, - "Timeout": 10000000000, - "StartPeriod": 30000000000, - "Retries": 3 - } - ``` - Note: - 1. Ensure the API Route exists in your application - 2. For Dockerfile deployments, ensure that - - your host is configured to listen to 127.0.0.1 (or 0.0.0.0). For example, for NextJS Dockerfile, ensure `ENV HOSTNAME=0.0.0.0` is set. - - your docker image has `curl` installed (this is not available by default on alpine-based images). Alternatively, you can use wget: - ```json - "Test": [ - "CMD", - "wget", - "--spider", - "-q", - "http://127.0.0.1:3000/api/health" - ], - ``` - -5. Next, in the `Update Config` field, copy and paste this code block: +Assuming you have already set up healthchecks for your application, you can additionally configure rollback using the steps below: + +1. Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings` +2. Locate the `Update Config` section. +3. Paste the code block below: ```json { "Parallelism": 1, @@ -58,4 +30,4 @@ Suppose we have a NodeJS application running on port 3000 with a health check ro } ``` -Now when the application is getting unhealthy response from the health check, the container will rollback to the previous version. \ No newline at end of file +Now, when the application is unhealthy from the health checks, the container will automatically roll back to a previous available version. \ No newline at end of file From 919688fd334572023ee561bfce59a2cb21d986c3 Mon Sep 17 00:00:00 2001 From: Tam Nguyen Date: Wed, 5 Feb 2025 14:46:50 +1100 Subject: [PATCH 5/9] fix: added alt for image zooms --- apps/docs/content/docs/core/applications/advanced.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/docs/content/docs/core/applications/advanced.mdx b/apps/docs/content/docs/core/applications/advanced.mdx index 9847eefd..bff48ae5 100644 --- a/apps/docs/content/docs/core/applications/advanced.mdx +++ b/apps/docs/content/docs/core/applications/advanced.mdx @@ -128,9 +128,9 @@ Configure persistent storage for your application to ensure data remains intact File mounts are a dokploy features, this create a file in a folder called `files` inside your project, so it recreates every single time you deploy your project. - + - + ### Redirects From 85d4bd1cba5c6a209d79b2a101560c1654a99b41 Mon Sep 17 00:00:00 2001 From: Tam Nguyen Date: Wed, 5 Feb 2025 14:51:21 +1100 Subject: [PATCH 6/9] fix: reduce repetition by referencing other sections --- .../core/applications/going-production.mdx | 47 ++----------------- 1 file changed, 5 insertions(+), 42 deletions(-) diff --git a/apps/docs/content/docs/core/applications/going-production.mdx b/apps/docs/content/docs/core/applications/going-production.mdx index 679e8efe..a618a1e8 100644 --- a/apps/docs/content/docs/core/applications/going-production.mdx +++ b/apps/docs/content/docs/core/applications/going-production.mdx @@ -3,6 +3,7 @@ title: Going Production description: Learn how to deploy your application in production in Dokploy. --- +import Link from 'next/link'; import { Callout } from 'fumadocs-ui/components/callout'; By default, dokploy offer multiple [Builds Types](/docs/core/applications/build-type) to deploy your application, the most common is `nixpacks` and `heroku buildpacks` @@ -166,48 +167,10 @@ jobs: You can also use this Github Action [Action](https://github.com/marketplace/actions/dokploy-deployment) to automate the deployment. -## Healthcheck & Rollbacks +## Zero-downtime (healthcheck) -When using Dokploy you can also configure healthchecks and rollbacks, this will allow you to configure your application to be able to recover from failures. - -In the repo we are using from the `Step 1.` we have a healthcheck endpoint `/health` that returns a 200 status code and running in the port 3000. +Please refer to the zero documentation. -Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings` +## Rollbacks -There are a couple options that you can use, in this case we will focus on `Health Check` and `Update Config`. - -Make sure the API Route exists in your application - -```json -{ - "Test": [ - "CMD", - "curl", - "-f", - "http://127.0.0.1:3000/health" - ], - "Interval": 30000000000, - "Timeout": 10000000000, - "StartPeriod": 30000000000, - "Retries": 3 -} -``` - -Now in the `Update Config` - -Now when the application is getting unhealthy response from the health check, the container will rollback to the previous version. - -Paste the following code: -```json -{ - "Parallelism": 1, - "Delay": 10000000000, - "FailureAction": "rollback", - "Order": "start-first" -} -``` - - -Now you everything a production ready application with automated deployments, zero downtime, rollbacks and healthchecks. - -We recommend strongly to use this approach in production since this will make your server never build the application, will only in charge of the deployment keeping your server without any downtime. \ No newline at end of file +Please refer to the rollbacks documentation. \ No newline at end of file From a8af310a656a49ba13c8bbe9ab16818e42976733 Mon Sep 17 00:00:00 2001 From: Tam Nguyen Date: Wed, 5 Feb 2025 14:53:14 +1100 Subject: [PATCH 7/9] docs: added notes about configuring rollbacks in zero downtime --- apps/docs/content/docs/core/applications/zero-downtime.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/apps/docs/content/docs/core/applications/zero-downtime.mdx b/apps/docs/content/docs/core/applications/zero-downtime.mdx index cffad7ca..b0c060f4 100644 --- a/apps/docs/content/docs/core/applications/zero-downtime.mdx +++ b/apps/docs/content/docs/core/applications/zero-downtime.mdx @@ -3,6 +3,8 @@ title: Zero Downtime description: Learn how to configure zero downtime deployments in Dokploy. --- +import Link from 'next/link'; + By default, when you create a new deployment, it will stop the latest running container and start the new one. This is the default behavior of Docker Swarm and this leads to Bad Gateway since the containers are initialized at the same time. @@ -44,6 +46,8 @@ To enable zero-downtime, ], ``` +Additionally, you are recommended to also configure rollbacks for your application in production. + ## Example - We will use this example [Github Repo](https://github.com/Dokploy/swarm-test) @@ -91,4 +95,3 @@ This configuration instructs Docker to: 5. Retry the health check 3 times before considering the container unhealthy. With this setup, new deployments will only replace old containers after the new instance passes health checks, preventing downtime 🎊. - From b5dda19a34c7ad2708cd6d10d13d07ffb6ad14f0 Mon Sep 17 00:00:00 2001 From: Tam Nguyen Date: Wed, 5 Feb 2025 15:23:33 +1100 Subject: [PATCH 8/9] fix: long form for wget -q, --quiet --- apps/docs/content/docs/core/applications/zero-downtime.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/content/docs/core/applications/zero-downtime.mdx b/apps/docs/content/docs/core/applications/zero-downtime.mdx index b0c060f4..bb69a675 100644 --- a/apps/docs/content/docs/core/applications/zero-downtime.mdx +++ b/apps/docs/content/docs/core/applications/zero-downtime.mdx @@ -40,8 +40,8 @@ To enable zero-downtime, "Test": [ "CMD", "wget", + "--quiet", "--spider", - "-q", "http://127.0.0.1:3000/api/health" ], ``` From 06b7d196af46666d83d0048d65041d612ae20902 Mon Sep 17 00:00:00 2001 From: Khiet Tam Nguyen Date: Wed, 5 Feb 2025 18:53:55 +1100 Subject: [PATCH 9/9] fix: use long form for curl -f to be explicit --- apps/docs/content/docs/core/applications/zero-downtime.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/docs/content/docs/core/applications/zero-downtime.mdx b/apps/docs/content/docs/core/applications/zero-downtime.mdx index bb69a675..eb5fb1c5 100644 --- a/apps/docs/content/docs/core/applications/zero-downtime.mdx +++ b/apps/docs/content/docs/core/applications/zero-downtime.mdx @@ -22,7 +22,7 @@ To enable zero-downtime, "Test": [ "CMD", "curl", - "-f", + "--fail", "http://127.0.0.1:3000/api/health" ], "Interval": 30000000000, @@ -76,7 +76,7 @@ To configure health checks for zero downtime. "Test": [ "CMD", "curl", - "-f", + "--fail", "http://localhost:3000/health" ], "Interval": 30000000000,