Dokploy/website
1
0
Fork 0
mirror of https://github.com/Dokploy/website synced 2025-06-26 18:16:01 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat: add production guides, zero downtime and rollbacks

Browse Source
This commit is contained in:
Mauricio Siu
2024-11-10 14:55:12 -06:00
parent 1701fc3852
commit f458c31178
3 changed files with 341 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
apps/docs/content/docs/core/applications/going-production.mdx Normal file
View File

@@ -0,0 +1,213 @@
---
title: Going Production
description: Learn how to deploy your application in production in Dokploy.
---
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`
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
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.
## Solution
You have two options to solve this problem:
1. Increase the resources of your server CPU, RAM, Disk (Probably is not a good idea and cheapest solution)
2. Build & Publish the application in a CI/CD pipeline eg. Github Actions, Gitlab CI, etc. (Recommended)
### Build & Publish the application in a CI/CD pipeline
We will use Github Actions as an example, but you can use any CI/CD pipeline that you want.
We will use the following configuration:
1. **Use Git Provider in Your Application**:
- Repository: `https://github.com/Dokploy/production-example`
- Branch: `main`
- Build path: `/`
<Callout type="info">
The repo have everything you need, however you can follow the same idea for your own applications.
</Callout>
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.
4. We will use `Dockerhub` as an example, but you can use any container registry that you want.
5. Make sure to create the repository in the `Dockerhub` , `namespace` is your username and `repository` is `example`.
6. Create a new Github Actions workflow in `.github/workflows/deploy.yml`
7. Add the following code to the workflow:
```yaml
name: Build Docker images
on:
push:
branches: ["main"]
jobs:
build-and-push-dockerfile-image:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Log in to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }} # Make sure to add the secrets in your repository in -> Settings -> Secrets (Actions) -> New repository secret
password: ${{ secrets.DOCKERHUB_TOKEN }} # Make sure to add the secrets in your repository in -> Settings -> Secrets (Actions) -> New repository secret
- name: Build and push Docker image
uses: docker/build-push-action@v4
with:
context: .
file: ./Dockerfile
push: true
# Make sure to replace with your own namespace and repository
tags: |
namespace/example:latest
platforms: linux/amd64
```
8. Create your own Dockerfile, in this case we will use the `Dockerfile` from the repository.
```properties
FROM node:18-alpine AS base
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable
FROM base AS build
WORKDIR /app
COPY . .
COPY package.json pnpm-lock.yaml ./
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
ENV NODE_ENV=production
RUN pnpm run build
FROM base AS dokploy
WORKDIR /app
ENV NODE_ENV=production
# Copy only the necessary files
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./package.json
COPY --from=build /app/node_modules ./node_modules
EXPOSE 3000
CMD ["pnpm", "start"]
```
9. Now when you make a commit to your repository, the workflow will be triggered and the application will build and push to `Dockerhub`.
10. Now let's create application in Dokploy.
11. In `Source Type` select `Docker`
12. In the docker image field enter `namespace/example:latest`
13. Click on `Save`.
14. Click on `Deploy`.
15. Go to `Domains` and click `Dices` icon to generate a domain and the port set to `3000`.
16. Now you can access your application.
### Auto deploy
When using Dockerhub as a registry you can also enable auto deploy, this will automatically deploy your application whenever you push to your repository.
To setup auto deploys for Dockerhub, follow the steps below:
1. Go to your application and select `Deployments` tab.
2. Copy the `Webhook URL`.
3. Go to your Dockerhub repository and select `Webhooks` tab.
4. Set a name for the webhook and paste the `Webhook URL` copied in step 2.
5. That's it, now every time you push to your repository, your application will trigger a deployment in dokploy.
The deployment will trigger only if the `Tag` matches the one specified in Dokploy.
#### External Registry
If you have a registry that is not Dockerhub, you can trigger a deployment after pushing to your repository in Github Actions.
Your workflow will look like this:
This method use the [Api Method](/docs/core/auto-deploy#api-method) to trigger a deployment.
```yaml
name: Build Docker images
on:
push:
branches: ["main"]
jobs:
build-and-push-dockerfile-image:
runs-on: ubuntu-latest
steps:
...Same as step 7 from the previous example
- name: Trigger Dokploy Deployment
uses: dokploy/dokploy-action@v1
run: |
curl -X 'POST' \
'https://<your-dokploy-domain>/api/trpc/application.deploy' \
-H 'accept: application/json' \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"json":{
"applicationId": "YOUR-APPLICATION-ID"
}
}'
```
You can also use this Github Action [Action](https://github.com/marketplace/actions/dokploy-deployment) to automate the deployment.
## Healthcheck & Rollbacks
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.
Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings`
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://localhost: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.

52
apps/docs/content/docs/core/applications/rollbacks.mdx Normal file
View File

@@ -0,0 +1,52 @@
---
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.
## Requirements
1. Have a `/health` endpoint in your application.
## 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.
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://localhost: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"
}
```

76
apps/docs/content/docs/core/applications/zero-downtime.mdx Normal file
View File

@@ -0,0 +1,76 @@
---
title: Zero Downtime
description: Learn how to configure zero downtime deployments in Dokploy.
---
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.
## 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://localhost:3000/api/health"
],
"Interval": 30000000000,
"Timeout": 10000000000,
"StartPeriod": 30000000000,
"Retries": 3
}
```
## Example
1. We will use this example [Github Repo](https://github.com/Dokploy/swarm-test)
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.
3. For testing purpose I've added a sleep to simulate the delay between the deployments and you can see the bad gateway error.
1. **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.
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
```json
{
"Test": [
"CMD",
"curl",
"-f",
"http://localhost:3000/health"
],
"Interval": 30000000000,
"Timeout": 10000000000,
"StartPeriod": 30000000000,
"Retries": 3
}
```
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
that would be all, Now you have Zero Downtime Deployments 🎊.