dokploy Documentation

1. Project Overview & Quickstart (Dokploy/dokploy) Copy Chapter

File: README.md Copy Chapter

Dokploy is a free, self-hostable Platform as a Service (PaaS) that simplifies the deployment and management of applications and databases.

✨ Features Copy Chapter

Dokploy includes multiple features to make your life easier.

• Applications: Deploy any type of application (Node.js, PHP, Python, Go, Ruby, etc.).
• Databases: Create and manage databases with support for MySQL, PostgreSQL, MongoDB, MariaDB, libsql, and Redis.
• Backups: Automate backups for databases to an external storage destination.
• Docker Compose: Native support for Docker Compose to manage complex applications.
• Multi Node: Scale applications to multiple nodes using Docker Swarm to manage the cluster.
• Templates: Deploy open-source templates (Plausible, Pocketbase, Calcom, etc.) with a single click.
• Traefik Integration: Automatically integrates with Traefik for routing and load balancing.
• Real-time Monitoring: Monitor CPU, memory, storage, and network usage for every resource.
• Docker Management: Easily deploy and manage Docker containers.
• CLI/API: Manage your applications and databases using the command line or through the API.
• Notifications: Get notified when your deployments succeed or fail (via Slack, Discord, Telegram, Email, etc.).
• Multi Server: Deploy and manage your applications remotely to external servers.
• Self-Hosted: Self-host Dokploy on your VPS.

🚀 Getting Started Copy Chapter

To get started, run the following command on a VPS:

Want to skip the installation process? Try the Dokploy Cloud.

curl -sSL https://dokploy.com/install.sh | bash

For detailed documentation, visit docs.dokploy.com.

Github Sponsors

Contributors 🤝 Copy Section

📺 Video Tutorial Copy Chapter

🤝 Contributing Copy Chapter

Check out the Contributing Guide for more information.

File: apps/monitoring/README.md Copy Chapter

Dokploy Monitoring (Go Version)

Application that powers Dokploy's monitoring service.

You can use it for monitoring any external service.

Requirements Copy Chapter

• Go 1.21

Configuration Copy Chapter

Create a .env file in the root of the project with the following content:

METRICS_CONFIG='{
  "server": {
    "refreshRate": 25,
    "port": 3001,
    "type": "Remote | Dokploy",
    "token": "metrics",
    "urlCallback": "http://localhost:3000/api/trpc/notification.receiveNotification",
    "retentionDays": 7,
    "cronJob": "0 0 * * *",
    "thresholds": {
      "cpu": 0,
      "memory": 0
    }
  },
  "containers": {
    "refreshRate": 25,
    "services": {
      "include": ["testing-elasticsearch-14649e"],
      "exclude": []
    }
  }
}'

Installation Copy Chapter

go mod download

Execution Copy Chapter

go run main.go

Endpoints Copy Chapter

• GET /health - Check service health status (no authentication required)
• GET /metrics?limit=<number|all> - Get server metrics (default limit: 50)
• GET /metrics/containers?limit=<number|all>&appName=<name> - Get container metrics for a specific application (default limit: 50)

Features Copy Chapter

Server Copy Section

• CPU Usage (%)
• Memory Usage (%)
• Disk
• Network
• CPU Model
• Operating System
• Kernel
• Architecture
• Threads

Example response:

Containers Copy Section

Compatible with all Docker container types (standalone containers, Docker Compose, and Docker Swarm stacks). Note: When monitoring Docker Compose or Swarm stacks, use the --p flag to properly identify all services within the stack.

Example response:

Metrics JSON:

{
  "timestamp": "2025-01-19T22:16:30.796129Z",
  "CPU": 83.76,
  "Memory": {
    "percentage": 0.03,
    "used": 2.262,
    "total": 7.654,
    "usedUnit": "MB",
    "totalUnit": "GB"
  },
  "Network": {
    "input": 306,
    "output": 0,
    "inputUnit": "B",
    "outputUnit": "B"
  },
  "BlockIO": {
    "read": 28.7,
    "write": 0,
    "readUnit": "kB",
    "writeUnit": "B"
  },
  "Container": "7428f5a49039",
  "ID": "7428f5a49039",
  "Name": "testing-elasticsearch-14649e-kibana-1"
}

Notifications Copy Chapter

Dokploy uses a callback URL to send notifications when metrics exceed configured thresholds. Notifications are sent via POST request in the following format:

Note: Setting a threshold to 0 disables notifications for that metric.

interface Notification {
  Type: "Memory" | "CPU";
  Value: number;
  Threshold: number;
  Message: string;
  Timestamp: string;
  Token: string;
}

File: packages/server/src/emails/readme.md Copy Chapter

React Email Starter

A live preview right in your browser so you don't need to keep sending real emails during development.

Getting Started Copy Chapter

First, install the dependencies:

npm install
# or
yarn

Then, run the development server:

npm run dev
# or
yarn dev

Open localhost:3000 with your browser to see the result.

License Copy Chapter

MIT License

2. Official Technical Reference & Guides (Dokploy/docs) Copy Chapter

File: README.md Copy Chapter

dokploy-docs

This is a Next.js application generated with
Create Fumadocs.

Run development server:

npm run dev
# or
pnpm dev
# or
yarn dev

Open http://localhost:3000 with your browser to see the result.

Learn More Copy Chapter

To learn more about Next.js and Fumadocs, take a look at the following
resources:

• Next.js Documentation - learn about Next.js
  features and API.
• Learn Next.js - an interactive Next.js tutorial.
• Fumadocs - learn about Fumadocs

File: content/docs/core/get-started/architecture.cn.mdx Copy Chapter

title: '架构' Copy Chapter

了解 Dokploy 的架构对于部署和扩展应用程序至关重要。以下是核心组件的示意图：

安装过程 Copy Chapter

安装 Dokploy 时，它会自动设置以下组件：

1. Next.js 应用程序：作为前端界面。利用 Next.js 提供集成的服务器端渲染体验，将 UI 和后端整合成一个统一的应用程序。
2. PostgreSQL 数据库：作为 Dokploy 的主要数据库，因其稳健性和广泛采用而被选用。它存储所有配置和操作数据。
3. Redis 数据库：用于管理部署队列。确保多个部署不会同时触发，避免服务器负载过高和潜在的冻结问题。
4. Traefik：用作反向代理和负载均衡器。Traefik 促进动态路由和服务发现，通过 UI 允许声明性设置，简化配置过程。

目的和功能 Copy Chapter

Dokploy 架构中的每个组件都扮演着重要角色：

• Next.js：提供可扩展且易于管理的前端框架，将服务器端和客户端逻辑封装在一个平台中，简化了部署和开发工作流。
• PostgreSQL：提供可靠和安全的数据存储能力。在 Dokploy 中的使用确保了所有数据库操作的一致性和高性能。
• Redis：处理并发和任务调度。通过使用 Redis，Dokploy 可以高效管理部署任务，避免在同时操作期间发生冲突和服务器过载。
• Traefik：增强 Docker 集成。其声明性地读取和写入 Docker 配置的能力，使 Dokploy 能够自动化和简化网络流量管理和服务发现。

这种结构确保了 Dokploy 不仅在部署应用程序时高效，而且在处理大规模流量和数据时也具有稳健性。

File: content/docs/core/get-started/architecture.mdx Copy Chapter

title: 'Architecture of Dokploy' Copy Chapter

Understanding the architecture of Dokploy is crucial for both deploying and scaling applications. Below is a diagram illustrating the core components:

Installation Process Copy Chapter

When Dokploy is installed, it automatically sets up the following components:

1. Next.js Application: Serves as the frontend interface. Utilizing Next.js allows for an integrated server-side rendering experience, streamlining the UI and backend into a single cohesive application.
2. PostgreSQL Database: Acts as the primary database for Dokploy, chosen for its robustness and widespread adoption. It stores all the configuration and operational data.
3. Redis Database: Employed for managing deployment queues. This ensures that multiple deployments do not trigger simultaneously, which could lead to high server load and potential freezing.
4. Traefik: Used as a reverse proxy and load balancer. Traefik facilitates dynamic routing and service discovery which simplifies the configuration process by allowing declarative setup through the UI.

Purpose and Functionality Copy Chapter

Each component in the Dokploy architecture plays a vital role:

• Next.js: Provides a scalable and easy-to-manage frontend framework, encapsulating both server and client-side logic in one platform. This simplifies deployment and development workflows.
• PostgreSQL: Delivers reliable and secure data storage capabilities. Its use within Dokploy ensures consistency and high performance for all database operations.
• Redis: Handles concurrency and job scheduling. By using Redis, Dokploy can efficiently manage deployment tasks, avoiding collisions and server overload during simultaneous operations.
• Traefik: Enhances Docker integration. Its ability to read from and write to Docker configurations declaratively allows Dokploy to automate and streamline network traffic management and service discovery.

This structure ensures that Dokploy is not only efficient in deploying applications but also robust in handling traffic and data at scale.

File: content/docs/core/get-started/features.cn.mdx Copy Chapter

title: '特点' Copy Chapter

Dokploy 提供了一套全面的功能，旨在简化和增强应用程序部署过程。

应用程序部署 Copy Chapter

Dokploy 支持两种主要的应用程序部署方法：

1. 应用程序：这种简单的方法允许轻松部署。对于单个应用程序而言，它提供了接近即插即用的体验。
2. Docker Compose：一种更高级的选项，需要创建 Dockerfiles 和 docker-compose.yml。此方法提供了更大的部署设置控制权和充分利用 Docker Compose 功能的能力。

应用程序管理 Copy Section

通过以下功能管理您的应用程序：

基本操作：

1. 部署、停止和删除应用程序。
2. 直接在应用程序容器中打开终端。

源代码和构建配置：

1. 选择源代码提供商（GitHub、Git、Docker）。
2. 选择构建类型（Docker、Nixpacks、Heroku Buildpacks、Paketo Buildpacks）。

环境管理：

1. 添加和管理环境变量。

监控工具：

1. 监控 CPU、内存、磁盘和网络使用情况。

日志：

1. 访问实时日志。

部署：

1. 查看和管理部署，可以查看构建应用程序的日志。
2. 取消排队的部署，如果您有很多部署在队列中，尤其是在您的存储库中多次推送时，您可以取消即将到来的队列，但不能取消已在运行的部署。

域名管理：

1. 添加、删除和生成域名。

高级设置：

1. 自定义初始命令和集群设置。
2. 设置资源限制和管理数据持久化的卷。
3. 配置重定向、安全标头和端口设置。
4. 根据具体需求详细配置 Traefik。

Docker Compose 管理 Copy Section

通过以下高级功能增强 Docker Compose 体验：

生命周期管理：

1. 部署、停止和删除 Docker Compose 设置。
2. 打开带有服务选择功能的终端。

源代码配置：

1. 选择源代码提供商（GitHub、Git、Raw）。

环境管理：

1. 添加和管理环境变量。

监控工具：

1. 监控每个服务的 CPU、内存、磁盘和网络使用情况。

日志：

1. 查看每个服务的实时日志。

部署：

1. 查看和管理部署，可以查看构建应用程序的日志。
2. 取消排队的部署，如果您有很多部署在队列中，尤其是在您的存储库中多次推送时，您可以取消即将到来的队列，但不能取消已在运行的部署。

高级设置：

1. 追加命令，默认情况下我们使用内部命令构建 Docker Compose，但您可以向现有命令追加命令。
2. 管理卷和挂载。

数据库部署 Copy Chapter

部署和管理各种数据库：

支持的数据库：

1. MySQL、PostgreSQL、MongoDB、Redis、MariaDB。

常规管理：

1. 部署、停止和删除数据库。
2. 在数据库容器内打开终端。

环境和监控：

1. 管理环境变量。
2. 监控 CPU、内存、磁盘和网络使用情况。

备份和日志：

1. 配置手动和计划备份。
2. 查看实时日志。

高级配置：

1. 使用自定义 Docker 镜像和初始命令。
2. 配置卷和资源限制。

这些功能旨在为您的部署环境提供灵活性和控制，确保 Dokploy 满足现代应用程序部署和管理的多样化需求。

File: content/docs/core/get-started/features.mdx Copy Chapter

title: 'Features' Copy Chapter

Dokploy provides a comprehensive suite of features designed to simplify and enhance the application deployment process.

Application Deployment Copy Chapter

Dokploy supports two primary methods for deploying applications:

1. Applications: This straightforward method allows for effortless deployment. Ideal for single applications, it offers a near plug-and-play experience.
2. Docker Compose: A more advanced option, requiring the creation of Dockerfiles and docker-compose.yml. This method provides greater control over deployment settings and full utilization of Docker Compose capabilities.

Applications Management Copy Section

Manage your applications through a range of features:

Basic Operations:

1. Deploy, stop, and delete applications.
2. Open a terminal directly in the application container.

Source and Build Configuration:

1. Choose source providers (GitHub, Git, Docker).
2. Select build types (Docker, Nixpacks, Heroku Buildpacks, Paketo Buildpacks).

Environment Management:

1. Add and manage environment variables.

Monitoring Tools:

1. Monitor CPU, memory, disk, and network usage.

Logs:

1. Access real-time logs.

Deployments:

1. View and manage deployments, you can see the logs of the building application.
2. Cancel queued deployments in case you have a lot of deployments in the queue, the most common is when you push alot of times in your repository, you can cancel the incoming queues, not the deployments that are already running.

Domain Management:

1. Add, delete, and generate domains.

Advanced Settings:

1. Customize initial commands and cluster settings.
2. Set resource limits and manage volumes for data persistence.
3. Configure redirects, security headers, and port settings.
4. Detailed Traefik configuration for specific needs.

Docker Compose Management Copy Section

Enhance your Docker Compose experience with these advanced functionalities:

Lifecycle Management:

1. Deploy, stop, and delete Docker Compose setups.
2. Open a terminal with service selection capability.

Source Configuration:

1. Choose source providers (GitHub, Git, Raw).

Environment Management:

1. Add and manage environment variables.

Monitoring Tools:

1. Monitor CPU, memory, disk, and network usage of each service.

Logs:

1. View real-time logs of each service.

Deployments:

1. View and manage deployments, you can see the logs of the building application.
2. Cancel queued deployments in case you have a lot of deployments in the queue, the most common is when you push alot of times in your repository, you can cancel the incoming queues, not the deployments that are already running.

Advanced Settings:

1. Append command, by default we use a internal command to build the docker compose however, you can append a command to the existing one.
2. Manage volumes and mounts.

Database Deployment Copy Chapter

Deploy and manage a variety of databases:

Supported Databases:

1. MySQL, PostgreSQL, MongoDB, Redis, MariaDB.

General Management:

1. Deploy, stop, and delete databases.
2. Open a terminal within the database container.

Environment and Monitoring:

1. Manage environment variables.
2. Monitor CPU, memory, disk, and network usage.

Backups and Logs:

1. Configure manual and scheduled backups.
2. View real-time logs.

Advanced Configuration:

1. Use custom Docker images and initial commands.
2. Configure volumes and resource limits.

These features are designed to offer flexibility and control over your deployment environments, ensuring that Dokploy meets the diverse needs of modern application deployment and management.

File: content/docs/core/get-started/installation.cn.mdx Copy Chapter

title: "安装" Copy Chapter

设置您的环境 Copy Chapter

按照以下步骤在本地设置 Dokploy 并将其部署到您的服务器， 管理 Docker 容器和应用程序：

{/* create a list please of the steps */}

您需要按照顺序执行以下步骤：

1. Virtual Private Server (VPS)
2. Docker

Virtual Private Server (VPS) Copy Chapter

有多个 VPS 提供商可供选择。以下是最常见的 VPS 提供商列表：

我们已经在两个 Linux Distros 上进行了测试：

• Ubuntu Server 20.04 LTS
• Debian 10

服务商 Copy Section

• DigitalOcean
• Hetzner
• Linode
• Vultr
• Scaleway
• Google Cloud
• AWS
• 阿里云
• 腾讯云

要求 Copy Section

为了确保 Dokploy 的流畅体验，您的服务器应该至少有 2 GB RAM 和 30 GB 磁盘空间。该规范有助于处理 Docker 在构建期间消耗的资源并防止系统假死。

import { Callout } from 'fumadocs-ui/components/callout';

Docker Copy Section

Dokploy 利用 Docker，因此在您的服务器上安装 Docker 至关重要。如果尚未安装 Docker，请使用以下命令自动安装：

curl -sSL https://dokploy.com/install.sh | sh

完成设置 Copy Chapter

运行安装脚本后，Dokploy 及其依赖项将在您的服务器上设置。以下是如何完成设置并开始使用 Dokploy：

访问 Dokploy Copy Section

打开您的网络浏览器并导航至 http：//your-ip-from-your-vps：3000。 您将被引导到初始设置页面，在其中您可以配置 Dokploy 的管理帐号。

初始配置 Copy Section

1. 创建管理员帐号: 填写必要的详细信息以设置您的管理员帐户。 该帐户将成为 Dokploy 的管理员帐户。

{/* */}

File: content/docs/core/get-started/installation.mdx Copy Chapter

title: Installation Copy Chapter

Follow these steps in order to set up Dokploy locally and deploy it to your server, effectively managing Docker containers and applications:

You need to follow this steps in the same order:

1. Virtual Private Server (VPS)

Virtual Private Server (VPS) Copy Chapter

There are multiple VPS providers to choose from:

We have tested on the following Linux Distros:

• Ubuntu 24.04 LTS
• Ubuntu 23.10
• Ubuntu 22.04 LTS
• Ubuntu 20.04 LTS
• Ubuntu 18.04 LTS
• Debian 12
• Debian 11
• Debian 10
• Fedora 40
• Centos 9
• Centos 8

Providers Copy Section

• DigitalOcean
• Hetzner
• Linode
• Vultr
• Scaleway
• Google Cloud
• AWS

Requirements Copy Section

To ensure a smooth experience with Dokploy, your server should have at least 2GB of RAM and 30GB of disk space. This specification helps to handle the resources consumed by Docker during builds and prevents system freezes.

import { Callout } from 'fumadocs-ui/components/callout';

Suggestion: For cost efficiency with reliable service, we recommend Hetzner as the best value-for-money VPS provider.

Docker Copy Section

Dokploy utilizes Docker, so it is essential to have Docker installed on your server. If Docker is not already installed, use the following command to install it automatically:

curl -sSL https://dokploy.com/install.sh | sh

Completing the Setup Copy Chapter

After running the installation script, Dokploy and its dependencies will be set up on your server. Here's how to finalize the setup and start using Dokploy:

Accessing Dokploy Copy Section

Open your web browser and navigate to http://your-ip-from-your-vps:3000. You will be directed to the initial setup page where you can configure the administrative account for Dokploy.

Initial Configuration Copy Section

1. Create an Admin Account: Fill in the necessary details to set up your administrator account. This account will be the admin account for Dokploy.

File: content/docs/core/get-started/introduction.cn.mdx Copy Chapter

title: Dokploy 文档 Copy Chapter

import { Card, Cards } from 'fumadocs-ui/components/card';

欢迎来到 Dokploy Copy Chapter

Dokploy 是一款稳定、易于使用的部署解决方案，旨在简化应用程序管理流程。 可将 Dokploy 视为 Heroku、Vercel 和 Netliify 等平台的免费可托管替代品, 使用稳定的 Docker 和灵活的 Traefik 构建.

为什么选择 Dokploy？ Copy Chapter

• 简单: 简单的设置、管理、部署。
• 灵活: 支持广泛的应用程序和数据库。
• 开源: 免费开源软件，可供任何人使用。

设置 Dokploy Copy Chapter

开始使用 Dokploy 很简单。 遵循我们的指南有效地安装和配置您的应用程序和数据库。

开始 Copy Chapter

跟随我，一起开始吧。

File: content/docs/core/get-started/introduction.mdx Copy Chapter

title: Welcome to Dokploy Copy Chapter

import { Card, Cards } from 'fumadocs-ui/components/card';

Dokploy is a stable, easy-to-use deployment solution designed to simplify the application management process. Think of Dokploy as your free self hostable alternative to platforms like Heroku, Vercel, and Netlify, leveraging the robustness of Docker and the flexibility of Traefik.

{/* */}

Why Choose Dokploy? Copy Chapter

• Simplicity: Easy setup and management of deployments.
• Flexibility: Supports a wide range of applications and databases.
• Open Source: Free and open-source software, available for anyone to use.

Setting up Dokploy Copy Chapter

Getting started with Dokploy is straightforward. Follow our guides to install and configure your applications and databases effectively.

Setting up Copy Chapter

Please go to get started.

File: content/docs/core/get-started/manual-installation.cn.mdx Copy Chapter

title: '手动安装' Copy Chapter

如果您希望自定义 Dokploy 在服务器上的安装，可以修改以下几个方面：

1. 为 Dokploy 使用特定端口 - 这对于避免与其他服务的冲突非常理想。
2. 选择特定版本的 Dokploy - 可以选择如 canary、latest 或特定 Docker 标签（例如 v0.0.1）版本。
3. 指定 Traefik 的 HTTP 和 HTTPS 端口 - 当与其他服务器（如 Nginx）一起运行时非常有用。

安装脚本 Copy Chapter

下面是一个在 Linux 服务器上安装 Dokploy 的 Bash 脚本。确保在非容器的 Linux 环境中以 root 身份运行，并确保端口 80 和 443 是空闲的。

/* Detailed source-code truncated for AI context efficiency. */

这个脚本包括对常见陷阱的检查，如果未安装 Docker 则安装 Docker，初始化 Docker Swarm，创建网络，然后拉取并部署 Dokploy。脚本运行后，它提供成功消息和访问 Dokploy 的说明。

这种结构化的格式清晰地列出了先决条件、步骤和安装后信息，使其对执行手动安装的用户来说非常友好和易于理解。

自定义安装 Copy Chapter

自定义 swarm 广播地址

docker swarm init 命令中的 --advertise-addr 参数指定了 Docker Swarm 管理节点应该向 Swarm 中的其他节点广播的 IP 地址或接口。其他节点使用该地址与管理节点通信。

默认情况下，此脚本使用通过 curl -s ifconfig.me 命令获得的服务器外部 IP 地址。但是，根据您的网络配置，特别是如果您的服务器有多个网络接口或如果您在私有网络中设置 Swarm，您可能需要自定义此地址。

要自定义 --advertise-addr 参数，请将以下行：
advertise_addr=$(curl -s ifconfig.me)

替换为您所需的 IP 地址或接口，例如：
advertise_addr="192.168.1.100"

:warning: 该 IP 地址应对将加入 Swarm 的所有节点可访问。

已有 Docker Swarm Copy Chapter

如果您的服务器上已经运行了 Docker Swarm，并且您想使用 Dokploy，可以使用以下命令加入它：

docker network create --driver overlay --attachable dokploy-network

mkdir -p /etc/dokploy

chmod -R 777 /etc/dokploy

docker pull dokploy/dokploy:latest

# 安装
docker service create \
  --name dokploy \
  --replicas 1 \
  --network dokploy-network \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  --mount type=bind,source=/etc/dokploy,target=/etc/dokploy \
  --publish published=3000,target=3000,mode=host \
  --update-parallelism 1 \
  --update-order stop-first \
  dokploy/dokploy:latest