Skip to content

Commit f458c31

Browse files
SiumauricioSiumauricio
committed
feat: add production guides, zero downtime and rollbacks
1 parent 1701fc3 commit f458c31

File tree

3 files changed

+341
-0
lines changed

3 files changed

+341
-0
lines changed

‎apps/docs/content/docs/core/applications/going-production.mdx‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
title: Going Production
3+
description: Learn how to deploy your application in production in Dokploy.
4+
---
5+
6+
import { Callout } from 'fumadocs-ui/components/callout';
7+
8+
By default, dokploy offer multiple [Builds Types](/docs/core/applications/build-type) to deploy your application, the most common is `nixpacks` and `heroku buildpacks`
9+
however this also comes with problems, first is the resources that are required to build your application which some times can lead to timeout on your server or even freezeing your server
10+
and all your application will be down for this reasson, this is mainly problem from `Docker` since the comsumption of resources such as RAM, CPU is very high to build an application.
11+
12+
13+
14+
## Solution
15+
16+
You have two options to solve this problem:
17+
18+
1. Increase the resources of your server CPU, RAM, Disk (Probably is not a good idea and cheapest solution)
19+
2. Build & Publish the application in a CI/CD pipeline eg. Github Actions, Gitlab CI, etc. (Recommended)
20+
21+
22+
### Build & Publish the application in a CI/CD pipeline
23+
24+
We will use Github Actions as an example, but you can use any CI/CD pipeline that you want.
25+
26+
We will use the following configuration:
27+
28+
1. **Use Git Provider in Your Application**:
29+
- Repository: `https://github.com/Dokploy/production-example`
30+
- Branch: `main`
31+
- Build path: `/`
32+
33+
<Callout type="info">
34+
The repo have everything you need, however you can follow the same idea for your own applications.
35+
36+
</Callout>
37+
38+
39+
3. The repository already have a Dockerfile, so we will use that, in the case your application is different create your own Dockerfile is required for this guide.
40+
4. We will use `Dockerhub` as an example, but you can use any container registry that you want.
41+
5. Make sure to create the repository in the `Dockerhub` , `namespace` is your username and `repository` is `example`.
42+
6. Create a new Github Actions workflow in `.github/workflows/deploy.yml`
43+
7. Add the following code to the workflow:
44+
45+
```yaml
46+
name: Build Docker images
47+
48+
on:
49+
push:
50+
branches: ["main"]
51+
52+
jobs:
53+
build-and-push-dockerfile-image:
54+
runs-on: ubuntu-latest
55+
56+
steps:
57+
- name: Checkout repository
58+
uses: actions/checkout@v3
59+
60+
- name: Log in to Docker Hub
61+
uses: docker/login-action@v2
62+
with:
63+
username: ${{ secrets.DOCKERHUB_USERNAME }} # Make sure to add the secrets in your repository in -> Settings -> Secrets (Actions) -> New repository secret
64+
password: ${{ secrets.DOCKERHUB_TOKEN }} # Make sure to add the secrets in your repository in -> Settings -> Secrets (Actions) -> New repository secret
65+
66+
- name: Build and push Docker image
67+
uses: docker/build-push-action@v4
68+
with:
69+
context: .
70+
file: ./Dockerfile
71+
push: true
72+
# Make sure to replace with your own namespace and repository
73+
tags: |
74+
namespace/example:latest
75+
platforms: linux/amd64
76+
```
77+
8. Create your own Dockerfile, in this case we will use the `Dockerfile` from the repository.
78+
79+
```properties
80+
FROM node:18-alpine AS base
81+
ENV PNPM_HOME="/pnpm"
82+
ENV PATH="$PNPM_HOME:$PATH"
83+
RUN corepack enable
84+
85+
FROM base AS build
86+
WORKDIR /app
87+
COPY . .
88+
COPY package.json pnpm-lock.yaml ./
89+
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
90+
ENV NODE_ENV=production
91+
RUN pnpm run build
92+
93+
FROM base AS dokploy
94+
WORKDIR /app
95+
ENV NODE_ENV=production
96+
97+
# Copy only the necessary files
98+
COPY --from=build /app/dist ./dist
99+
COPY --from=build /app/package.json ./package.json
100+
COPY --from=build /app/node_modules ./node_modules
101+
102+
EXPOSE 3000
103+
CMD ["pnpm", "start"]
104+
```
105+
106+
9. Now when you make a commit to your repository, the workflow will be triggered and the application will build and push to `Dockerhub`.
107+
10. Now let's create application in Dokploy.
108+
11. In `Source Type` select `Docker`
109+
12. In the docker image field enter `namespace/example:latest`
110+
13. Click on `Save`.
111+
14. Click on `Deploy`.
112+
15. Go to `Domains` and click `Dices` icon to generate a domain and the port set to `3000`.
113+
16. Now you can access your application.
114+
115+
### Auto deploy
116+
117+
When using Dockerhub as a registry you can also enable auto deploy, this will automatically deploy your application whenever you push to your repository.
118+
119+
To setup auto deploys for Dockerhub, follow the steps below:
120+
121+
1. Go to your application and select `Deployments` tab.
122+
2. Copy the `Webhook URL`.
123+
3. Go to your Dockerhub repository and select `Webhooks` tab.
124+
4. Set a name for the webhook and paste the `Webhook URL` copied in step 2.
125+
5. That's it, now every time you push to your repository, your application will trigger a deployment in dokploy.
126+
127+
The deployment will trigger only if the `Tag` matches the one specified in Dokploy.
128+
129+
130+
#### External Registry
131+
132+
If you have a registry that is not Dockerhub, you can trigger a deployment after pushing to your repository in Github Actions.
133+
134+
Your workflow will look like this:
135+
136+
This method use the [Api Method](/docs/core/auto-deploy#api-method) to trigger a deployment.
137+
138+
```yaml
139+
name: Build Docker images
140+
141+
on:
142+
push:
143+
branches: ["main"]
144+
145+
jobs:
146+
build-and-push-dockerfile-image:
147+
runs-on: ubuntu-latest
148+
149+
steps:
150+
...Same as step 7 from the previous example
151+
152+
- name: Trigger Dokploy Deployment
153+
uses: dokploy/dokploy-action@v1
154+
run: |
155+
curl -X 'POST' \
156+
'https://<your-dokploy-domain>/api/trpc/application.deploy' \
157+
-H 'accept: application/json' \
158+
-H 'Authorization: Bearer YOUR-TOKEN' \
159+
-H 'Content-Type: application/json' \
160+
-d '{
161+
"json":{
162+
"applicationId": "YOUR-APPLICATION-ID"
163+
}
164+
}'
165+
```
166+
167+
You can also use this Github Action [Action](https://github.com/marketplace/actions/dokploy-deployment) to automate the deployment.
168+
169+
## Healthcheck & Rollbacks
170+
171+
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.
172+
173+
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.
174+
175+
Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings`
176+
177+
There are a couple options that you can use, in this case we will focus on `Health Check` and `Update Config`.
178+
179+
Make sure the API Route exists in your application
180+
181+
```json
182+
{
183+
"Test": [
184+
"CMD",
185+
"curl",
186+
"-f",
187+
"http://localhost:3000/health"
188+
],
189+
"Interval": 30000000000,
190+
"Timeout": 10000000000,
191+
"StartPeriod": 30000000000,
192+
"Retries": 3
193+
}
194+
```
195+
196+
Now in the `Update Config`
197+
198+
Now when the application is getting unhealthy response from the health check, the container will rollback to the previous version.
199+
200+
Paste the following code:
201+
```json
202+
{
203+
"Parallelism": 1,
204+
"Delay": 10000000000,
205+
"FailureAction": "rollback",
206+
"Order": "start-first"
207+
}
208+
```
209+
210+
211+
Now you everything a production ready application with automated deployments, zero downtime, rollbacks and healthchecks.
212+
213+
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.

‎apps/docs/content/docs/core/applications/rollbacks.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Rollbacks
3+
description: Learn how to rollback your application in Dokploy.
4+
---
5+
6+
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.
7+
8+
9+
## Requirements
10+
11+
1. Have a `/health` endpoint in your application.
12+
13+
## Steps to Rollback
14+
15+
16+
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.
17+
18+
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.
19+
2. Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings`
20+
3. There are a couple options that you can use, in this case we will focus on `Health Check` and `Update Config`.
21+
4. Paste this code in the health check field:
22+
Make sure the API Route exists in your application
23+
24+
```json
25+
{
26+
"Test": [
27+
"CMD",
28+
"curl",
29+
"-f",
30+
"http://localhost:3000/api/health"
31+
],
32+
"Interval": 30000000000,
33+
"Timeout": 10000000000,
34+
"StartPeriod": 30000000000,
35+
"Retries": 3
36+
}
37+
```
38+
5. Now in the `Update Config`
39+
40+
Now when the application is getting unhealthy response from the health check, the container will rollback to the previous version.
41+
42+
Paste the following code:
43+
```json
44+
{
45+
"Parallelism": 1,
46+
"Delay": 10000000000,
47+
"FailureAction": "rollback",
48+
"Order": "start-first"
49+
}
50+
```
51+
52+

‎apps/docs/content/docs/core/applications/zero-downtime.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Zero Downtime
3+
description: Learn how to configure zero downtime deployments in Dokploy.
4+
---
5+
6+
7+
Dokploy allows you to configure zero downtime deployments, which means that you can deploy your application without any downtime.
8+
9+
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
10+
the containers are initializing at the same time,
11+
but Dokploy allows you to configure zero downtime deployments.
12+
13+
## Steps to configure Zero Downtime Deployments
14+
15+
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.
16+
17+
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.
18+
2. Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings`
19+
3. There are a couple options that you can use, in this case we will focus on `Health Check`.
20+
4. Paste this code in the health check field:
21+
Make sure the API Route exists in your application
22+
23+
```json
24+
{
25+
"Test": [
26+
"CMD",
27+
"curl",
28+
"-f",
29+
"http://localhost:3000/api/health"
30+
],
31+
"Interval": 30000000000,
32+
"Timeout": 10000000000,
33+
"StartPeriod": 30000000000,
34+
"Retries": 3
35+
}
36+
```
37+
38+
## Example
39+
40+
1. We will use this example [Github Repo](https://github.com/Dokploy/swarm-test)
41+
2. It Have a endpoint called `health` [enbpoint](https://github.com/Dokploy/swarm-test/blob/main/index.js#L20) which is the one that will tell us if our application is healthy.
42+
3. For testing purpose I've added a sleep to simulate the delay between the deployments and you can see the bad gateway error.
43+
44+
45+
1. **Use Git Provider in Your Application**:
46+
- Repository: `https://github.com/Dokploy/swarm-test`
47+
- Branch: `main`
48+
- Build path: `/`
49+
50+
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.
51+
52+
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.
53+
54+
We will use this configuration specifically, paste and save it
55+
56+
```json
57+
{
58+
"Test": [
59+
"CMD",
60+
"curl",
61+
"-f",
62+
"http://localhost:3000/health"
63+
],
64+
"Interval": 30000000000,
65+
"Timeout": 10000000000,
66+
"StartPeriod": 30000000000,
67+
"Retries": 3
68+
}
69+
```
70+
71+
This configuration basically tells to Docker to do:
72+
73+
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
74+
75+
that would be all, Now you have Zero Downtime Deployments 🎊.
76+

0 commit comments

Comments
 (0)