# Application The Dokploy CLI can be used to create, deploy, and manage applications. ## Requirements Is required to be already authenticated with the Dokploy CLI. ## Commands 1. `dokploy app create` - Create a new application. 2. `dokploy app delete` - Delete an application. 3. `dokploy app deploy` - Deploy an application. 4. `dokploy app stop` - Stop a running application. # Authentication The Dokploy CLI uses a token-based authentication system. To authenticate, you'll need to create an access token and store it securely. ## Creating an Access Token To create an access token, first you need to have permissions if you are admin you don't need permissions. By default, an access token never expires, but you can optionally set an expiration date when creating it — recommended if the token will be used by a script, CI job, or anything outside your own machine. You can go to `dashboard/settings/profile` and click on the `Generate` button. ## Storing the Access Token Dokploy when you create an access token automatically will generate a config.json with the access token and the server url. ## Commands 1. `dokploy auth -u -t ` - Authenticate with the Dokploy CLI. 2. `dokploy verify` - Verify if the access token is valid. # Databases The Dokploy CLI can be used to create, deploy, and manage databases. ## Requirements Is required to be already authenticated with the Dokploy CLI. ## Commands ### MariaDB 1. `dokploy database mariadb create` - Create a new mariadb database. 2. `dokploy database mariadb delete` - Delete an mariadb database. 3. `dokploy database mariadb deploy` - Deploy a mariadb database. 4. `dokploy database mariadb stop` - Stop a running mariadb database. ### PostgreSQL 1. `dokploy database postgresql create` - Create a new postgresql database. 2. `dokploy database postgresql delete` - Delete an postgresql database. 3. `dokploy database postgresql deploy` - Deploy a postgresql database. 4. `dokploy database postgresql stop` - Stop a running postgresql database. ### MySQL 1. `dokploy database mysql create` - Create a new mysql database. 2. `dokploy database mysql delete` - Delete an mysql database. 3. `dokploy database mysql deploy` - Deploy a mysql database. 4. `dokploy database mysql stop` - Stop a running mysql database. ### MongoDB 1. `dokploy database mongodb create` - Create a new mongodb database. 2. `dokploy database mongodb delete` - Delete an mongodb database. 3. `dokploy database mongodb deploy` - Deploy a mongodb database. 4. `dokploy database mongodb stop` - Stop a running mongodb database. ### Redis 1. `dokploy database redis create` - Create a new redis database. 2. `dokploy database redis delete` - Delete an redis database. 3. `dokploy database redis deploy` - Deploy a redis database. 4. `dokploy database redis stop` - Stop a running redis database. # Enviroment The Dokploy CLI can be used to create, deploy, and manage enviroments. ## Requirements Is required to be already authenticated with the Dokploy CLI. ## Commands 1. `dokploy env pull ` - Pull environment variables from Dokploy in a file. 2. `dokploy env push ` - Push environment variables to Dokploy from a file. # Introduction Dokploy CLI is a command-line tool for remotely managing your Dokploy server. It simplifies creating, deploying, and managing applications and databases. ## Installation ```bash npm install -g @dokploy/cli ``` ## Usage ```bash dokploy COMMAND ``` To get help on a specific command: ```bash dokploy COMMAND --help ``` # Project The Dokploy CLI can be used to create, deploy, and manage projects. ## Requirements Is required to be already authenticated with the Dokploy CLI. ## Commands 1. `dokploy project create` - Create a new project. 2. `dokploy project info` - Get information about a project. 3. `dokploy project list` - List all projects. # Dokploy API In some cases, you may need to interact directly with the dokploy API. Here's how both administrators and users can do this. ## For Administrators 1. Access the Swagger UI by navigating to `your-vps-ip:3000/swagger`. 2. Use the Swagger interface to interact with the API. 3. By default, access to the Swagger UI is restricted, and only authenticated administrators can access the API. ## For Users 1. By default, users do not have direct access to the API. 2. Administrators can grant users access to: * Generate access tokens * Access the Swagger UI 3. If you need access, contact your administrator. Note: The API provides advanced functionalities. Make sure you understand the operations you're performing to avoid unintended changes to the system. ## Usage By default the OpenApi base url is `http://localhost:3000/api`, you need to replace with the ip of your dokploy instance or the domain name. ### Authentication The API uses JWT tokens for authentication. You can generate a token by going to the `/settings/profile` page and go to API/CLI Section and generate the token. Let's take a example of authenticated request: ```bash curl -X 'GET' \ 'https://dokploy.com/api/project.all' \ -H 'accept: application/json' \ -H 'x-api-key: YOUR-GENERATED-API-KEY' ``` then you will get the something like this: ```json [ { "projectId": "klZKsyw5g-QT_jrWJ5T-w", "name": "Random", "description": "", "createdAt": "2024-06-19T15:05:58.785Z", "adminId": "_WrKZbs7iJAA3p4N2Yfyu", "applications": [], "mariadb": [], "mongo": [], "mysql": [ { "mysqlId": "N3cudwO46TiDXzBm4SaQ1", "name": "mysql", "appName": "random-mysql-924715", "description": "", "databaseName": "mysql", "databaseUser": "mysql", "databasePassword": "h13BzO6y3KYSHaQg", "databaseRootPassword": "mM1b7JeoPA7jArxj", "dockerImage": "mysql:8", "command": null, "env": null, "memoryReservation": null, "memoryLimit": null, "cpuReservation": null, "cpuLimit": null, "externalPort": null, "applicationStatus": "done", "createdAt": "2024-06-24T01:55:40.378Z", "projectId": "klZKsyw5g-QT_jrWJ5T-w" } ], "postgres": [], "redis": [ { "redisId": "TtFK5S4QFaIjaNGOb8Ku-", "name": "redis", "appName": "random-redis-7eec62", "description": "", "databasePassword": "Yvb8gqClfomjcue8", "dockerImage": "redis:7", "command": null, "env": null, "memoryReservation": null, "memoryLimit": null, "cpuReservation": null, "cpuLimit": null, "externalPort": 6379, "createdAt": "2024-06-26T06:43:20.570Z", "applicationStatus": "done", "projectId": "klZKsyw5g-QT_jrWJ5T-w" } ], "compose": [] }, ] ``` # Account Security import { Callout } from "fumadocs-ui/components/callout"; Dokploy supports two mechanisms to secure panel access, and they can be combined: **passkeys** for passwordless sign-in and **two-factor authentication (2FA)** on top of password logins. ## Passkeys Passkeys are a passwordless sign-in method based on WebAuthn. Instead of typing a password (and a 2FA code), you authenticate with your device — Touch ID, Face ID, Windows Hello, or a hardware security key like a YubiKey. The credential never leaves your device and is resistant to phishing: it only works on your Dokploy panel's domain. ### Registering a passkey 1. Go to **Settings → Profile**. 2. In the **Passkeys** section, click add and follow your browser's prompt (fingerprint, face, PIN, or security key). 3. Give it a recognizable name — you can register several (e.g. laptop + phone) and remove them individually at any time. ### Signing in On the login page, use the passkey option and pick the credential — no password or 2FA code required. Register at least two passkeys (or keep your password + 2FA working) so losing a device doesn't lock you out. ## Two-Factor Authentication (2FA) 2FA adds a time-based one-time code (TOTP) to password logins, from any authenticator app (Google Authenticator, 1Password, Authy, etc.). ### Enabling 2FA 1. Go to **Settings → Profile**. 2. In the **2FA** section, click enable and scan the QR code with your authenticator app. 3. Confirm with a generated code, and store the backup codes somewhere safe — they are the recovery path if you lose the authenticator. Once enabled, password sign-ins require the current code from your app. ## Which one should I use? * **Passkeys** are the strongest and most convenient option — phishing-resistant and no codes to type. Prefer them for day-to-day sign-in. * **2FA** protects the password flow, which remains available as a fallback. If you keep using passwords, enable it. * Using both gives you a secure fallback chain: passkey for daily use, password + 2FA if a device is unavailable. Organization owners on Dokploy Cloud and self-hosted instances with SSO can additionally enforce sign-in through their identity provider — see the SSO documentation. # AI Assistant import { Callout } from 'fumadocs-ui/components/callout'; Dokploy integrates with AI providers to let you generate Docker Compose templates from natural language. Describe what you want to deploy, and the AI generates the configuration for you. Dokploy does not include its own AI model. You need to connect an external provider (like OpenAI, Anthropic, or any OpenAI-compatible API) with your own API key. ## Setting up an AI provider 1. Go to **Settings**. 2. Navigate to the **AI** section. 3. Click **Add AI Provider**. 4. Fill in the configuration: | Field | Description | | ----------- | ----------------------------------------------------------------- | | **Name** | A label for this provider (e.g., "OpenAI", "Claude", "Local LLM") | | **API URL** | The API endpoint (e.g., `https://api.openai.com/v1` for OpenAI) | | **API Key** | Your API key for authentication | | **Model** | The model to use (e.g., `gpt-4o`, `claude-sonnet-4-20250514`) | 5. Click **Save**. You can configure multiple providers and switch between them. ### Compatible providers Any provider that exposes an **OpenAI-compatible API** works with Dokploy. Some examples: | Provider | API URL | Models | | ------------------ | -------------------------------------------- | --------------------------------------------------------- | | **OpenAI** | `https://api.openai.com/v1` | gpt-4o, gpt-4o-mini, o1, etc. | | **Anthropic** | `https://api.anthropic.com/v1` | claude-sonnet-4-20250514, claude-haiku-4-5-20251001, etc. | | **Ollama** (local) | `http://localhost:11434/v1` | llama3, mistral, codellama, etc. | | **OpenRouter** | `https://openrouter.ai/api/v1` | Multiple providers through one API | | **Azure OpenAI** | `https://{resource}.openai.azure.com/openai` | gpt-4o, gpt-4, etc. | ## Generating Docker Compose templates Once you have a provider configured, you can use AI to generate Docker Compose templates when creating a new Compose service. ### How it works 1. Create a new **Docker Compose** service. 2. Click the **AI Generate** button. 3. Describe what you want to deploy in natural language. 4. The AI generates a complete `docker-compose.yml` with: * Service definitions * Environment variables with sensible defaults * Volumes and networks * Any additional config needed 5. Review and edit the generated configuration as needed. 6. Deploy. ### Example prompts * "A WordPress site with MySQL and Redis for caching" * "Grafana with Prometheus for monitoring" * "A Node.js API with MongoDB and Redis" * "Plausible Analytics with PostgreSQL and ClickHouse" * "Gitea with a PostgreSQL database" Always review the generated configuration before deploying. The AI provides a starting point — you may need to adjust environment variables, resource limits, or volumes for your specific use case. ## Managing providers You can manage your AI providers from **Settings → AI**: * **Add** multiple providers for different use cases * **Edit** existing provider configurations * **Delete** providers you no longer need * **View available models** for each provider * **Enable/Disable** providers without deleting them # Architecture of Dokploy Understanding the architecture of Dokploy is crucial for both deploying and scaling applications. Below is a diagram illustrating the core components: ## Installation Process 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. **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 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. * **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. # Auto Deploy ## Supported Services: Auto deploy is only valid for the following services: * Applications * Docker Compose ## Github For Github, we provide autodeploy without any configuration. This will automatically deploy your application whenever you push to your repository. ## Webhook URL Webhooks allow you to automatically deploy your application whenever changes are made in your source repository. * GitHub * GitLab * Bitbucket * Gitea * DockerHub (Only for Applications) ### Configuration Steps 1. **Enable Auto Deploy**: Toggle the 'Auto Deploy' button found in the general tab of your application settings in Dokploy. 2. **Obtain Webhook URL**: Locate the Webhook URL from the deployment logs. 3. **Configure Your Repository**: * Navigate to your repository settings on your chosen platform. * Add the webhook URL provided by Dokploy. * Ensure the settings match the configuration necessary for triggering the webhook. #### Important Notes * **Branch Matching**: When using Git-based providers (GitHub, GitLab, Gitea, etc.), ensure that the branch configured in Dokploy matches the branch you intend to push to. Misalignment will result in a "Branch Not Match" error. * **Docker Tags**: For deployments using DockerHub, ensure the tag pushed matches the one specified in Dokploy. * The steps are the same for all the providers. The steps are almost the same for all the Git providers, GitHub, GitLab, Bitbucket, Gitea. ## Dockerhub (Only Applications) 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. ## API Method Deploy your application programmatically using the Dokploy API from anywhere, this is useful when you want to trigger a deployment from a CI/CD pipeline or from a script. ### Steps to Deploy Using API Steps: 1. **Generate a Token**: Create an API token in your profile settings on Dokploy. 2. **Retrieve Application ID**: ```http curl -X 'GET' \ 'https://your-domain/api/project.all' \ -H 'accept: application/json' \ -H 'x-api-key: ' ``` This command lists all projects and services. Identify the applicationId for the application you wish to deploy. 3. **Trigger Deployment**: ```http curl -X 'POST' \ 'https://your-domain/api/application.deploy' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'x-api-key: ' \ -d '{ "applicationId": "string" }' ``` This API method allows for flexible, scriptable deployment options, suitable for automated systems or situations where direct repository integration is not feasible. In this way you can deploy your application from anywhere, you can use the webhook URL or the API. # Backups import { Callout } from 'fumadocs-ui/components/callout'; Dokploy provides a comprehensive backup and restore system that saves your entire Dokploy file system and database to ensure your data is safe and recoverable. ## Prerequisites Before using the backup feature, you need to have an S3 destination configured in your system. This is where your backups will be stored. ## Creating Backups To create a backup: 1. Navigate to Web Server → Backups 2. Select "Create Backup" 3. Choose your S3 destination 4. Configure the backup schedule using cron syntax (optional) When a backup is created, Dokploy will: * Back up the PostgreSQL database (`dokploy-postgres`) * Save the Dokploy file system (`/etc/dokploy`) * Combine and compress both into a single backup file (.zip) * Upload the backup to your specified S3 destination ## Restoring Backups To restore a backup: 1. Navigate to Web Server → Backups 2. Select "Restore Backup" 3. Choose the S3 destination containing your backup 4. Browse and select the backup file you want to restore 5. Review the summary of files to be restored During restoration, Dokploy will: * Clear the existing `/etc/dokploy` directory and replace it with the backup contents * Drop the existing `dokploy-postgres` database * Disconnect current database users * Restore the database from the backup After restoration is complete, you may need to log in again. If necessary, you can restart Traefik to ensure all services are properly configured. ## Post-Restoration Steps After restoring a backup, especially if you're restoring to a different server, consider the following: 1. If your server IP has changed: * Update the IP address in Web Server → Server → Update IP * Reconfigure Git providers if they were set up using IP addresses * Update your DNS records to point to the new IP * Recreate Traefik.me domains if you're using them 2. If you're using domain names instead of IPs for Git providers, no additional configuration is needed. # Certificates import { Callout } from 'fumadocs-ui/components/callout'; Dokploy offers a UI to manage your certificates. We expose a UI to create and delete the certificates, we ask two fields: 1. **Name**: Enter a name for the certificate (this can be anything you choose). 2. **Certificate Data**: Provide the certificate details. 3. **Private Key**: Enter the private key. 4. **(Optional) Server**: If you want to create a certificate for a server, you can select it here. This action will create the files, but that doesn't mean it will work automatically. You need to adjust the Traefik configuration to use it, this configuration will make to traefik can recognize the certificate. ## Traefik.me HTTPS Setup By default, all the domains from `traefik.me` are HTTP only, if you want to use HTTPS you need to create a certificate and use it in the domain settings. You need to download the full [https://traefik.me/fullchain.pem](https://traefik.me/fullchain.pem) and [https://traefik.me/privkey.pem](https://traefik.me/privkey.pem), this are valid for 30 days.s The fullchain.pem paste in the `Certificate Data` field and the privkey.pem paste in the `Private Key` field. Now when using the traefik.me domains, make sure to enable `HTTPS` toggle and select the certificate provider set `None` If you want to remove the certificate, just remove the certificate and in your domains settings remove the `HTTPS` toggle. # Dokploy Cloud import { Callout } from 'fumadocs-ui/components/callout'; Dokploy Cloud is the managed version of Dokploy. Instead of installing and maintaining Dokploy on your own server, the **control plane** (UI, database, and management layer) is hosted by us — you just connect your own servers and deploy. ## How it works With **Self-Hosted** Dokploy, everything runs on a single server: the UI, the database (PostgreSQL), Redis, Traefik, and your applications — all on the same machine. This works well for small setups, but as you scale, your management layer competes for resources with your actual workloads. **Dokploy Cloud** separates these concerns: ``` ┌──────────────────────────────┐ ┌─────────────────────────┐ │ Dokploy Cloud │ │ Your Server(s) │ │ (managed by Dokploy) │ │ (any cloud provider) │ │ │ │ │ │ ┌────────────┐ │ │ ┌───────────────────┐ │ │ │ Dashboard │─── deploy ──┼──────►│ │ Your apps │ │ │ │ (UI) │ │ │ │ Your databases │ │ │ ├────────────┤ │ │ │ Your compose │ │ │ │ PostgreSQL │ │ │ │ Traefik (proxy) │ │ │ ├────────────┤ │ │ └───────────────────┘ │ │ │ Redis │ │ │ │ │ └────────────┘ │ │ ┌───────────────────┐ │ │ │ │ │ Monitoring agent │ │ │ ┌────────────┐ │◄──────┤ │ (metrics → cloud) │ │ │ │ Monitoring │ │ │ └───────────────────┘ │ │ └────────────┘ │ │ │ └──────────────────────────────┘ └─────────────────────────┘ ``` * **Control plane** (Cloud): Dashboard, user management, deployment orchestration, monitoring dashboard, and notifications. * **Data plane** (Your servers): Your actual applications, databases, Traefik, and a lightweight monitoring agent. Your code and data **never leave your servers**. Dokploy Cloud only manages the orchestration. ## Key benefits | Benefit | Description | | --------------------------------------- | ---------------------------------------------------------------------------------------------------- | | **No management overhead** | No need to maintain the Dokploy instance itself — updates, backups, and uptime are handled for you | | **100% server resources for your apps** | The UI and management database don't compete with your workloads | | **Multi-server from day one** | Connect as many servers as you need from any provider (AWS, GCP, Azure, DigitalOcean, Hetzner, etc.) | | **Automatic updates** | Always on the latest version of Dokploy without manual upgrades | | **Support** | Direct support via email/chat (Startup) or priority SLA (Enterprise) | ## Getting started 1. Register on [Dokploy Cloud](https://app.dokploy.com). 2. Add a server by providing the SSH connection details (IP, port, SSH key). 3. Dokploy Cloud will set up the server automatically (Docker, Traefik, monitoring agent). 4. Start deploying your applications, databases, and compose stacks. You can connect servers from **any provider** — they just need to be reachable via SSH. You can even mix providers (e.g., Hetzner for production, DigitalOcean for staging). ## Pricing Dokploy Cloud offers several plans: | Plan | Price | Servers included | Additional servers | | -------------- | ---------------------- | ---------------- | -------------------- | | **Hobby** | $4.50/month per server | 1 | $4.50/month each | | **Startup** | $15/month | 3 | $4.50/month each | | **Enterprise** | Custom | Custom | Contact sales | | **Agency** | Custom | Custom | Contact partner team | All plans include **unlimited deployments, databases, and applications** per server. Annual billing saves 20%. See the [Pricing](https://dokploy.com/pricing) page for full plan details and feature limits. ## When to use Cloud vs Self-Hosted | Use Cloud when... | Use Self-Hosted when... | | ------------------------------------------------- | --------------------------------------------------- | | You don't want to maintain the Dokploy instance | You want full control over everything | | You need multi-server from the start | You have a single server and want to keep it simple | | You want built-in monitoring without extra config | You already have your own monitoring stack | | You prefer automatic updates | You want to control when updates happen | | You need HA for the management layer | Budget is the top priority | For a full feature comparison, see [Cloud vs Self-Hosted Differences](/docs/core/differences). # Cluster import { Callout } from "fumadocs-ui/components/callout"; Not sure whether you need Swarm nodes, remote servers, or a single Dokploy server? See [Deployment Options](/docs/core/deployment-options) for a comparison. When you deploy applications in dokploy, all of them run on the same node. If you wish to run an application on a different server, you can use the cluster feature. The idea of using clusters is to allow each server to host a different application and, using Traefik along with the load balancer, redirect the traffic from the dokploy server to the servers you choose. ## Server Scaling Methods There are two primary ways to scale your server: 1. **Vertical Scaling**: This involves adding more resources to the same dokploy server, such as more CPU and RAM. 2. **Horizontal Scaling**: This method involves adding multiple servers. ### Vertical Scaling We recommend using vertical scaling to increase the processing capacity of your applications since it's faster and requires less additional configuration. To perform vertical scaling, you need to add more resources to your dokploy server, that is, more CPU and RAM. This is done through your VPS provider. It's ideal to first check the vertical scaling limit you can handle. If you find it insufficient, you may consider horizontal scaling. ### Horizontal Scaling Horizontal scaling usually requires more additional configuration and involves adding more servers (VPS). If you choose the second option, we will proceed to configure the different servers. ## Requirements for Cluster Setup 1. dokploy server running (Manager). 2. Have at least one extra server with the same architecture as the dokploy server. 3. Have a Docker registry. ## Configuring the Docker Registry To start, we need to configure a Docker registry, as when deploying an application, you need a registry to deploy and download the application image on the other servers. ### External Registry You can use any external registry of your choice. Here are some popular options: 1. **Docker Hub** - Free tier available, easy to set up 2. **GitHub Container Registry (ghcr.io)** - Free for public repositories 3. **DigitalOcean Container Registry** - Simple setup with good integration 4. **Amazon ECR** - AWS's managed container registry 5. **Google Container Registry** - Google Cloud's managed registry 6. **Azure Container Registry** - Microsoft's managed registry Make sure to enter the correct credentials and test the connection before adding the registry to your cluster configuration. Once configured, the Cluster section will be unlocked. ## Understanding Docker Swarm We suggest you read this information to better understand how Docker Swarm works and its orchestration: [Docker Swarm documentation](https://docs.docker.com/engine/swarm/) and its architecture: [How Swarm mode works](https://docs.docker.com/engine/swarm/how-swarm-mode-works/nodes/). ## Managing Your Cluster Now you can do two things: 1. Add workers. 2. Add managers. Managers have two functionalities: 1. Manage the cluster state. 2. Schedule the services. Workers have a single purpose, which is to run the containers, acting under the rules created or established by the manager. ## Adding Nodes You can click the 'Add Node' button, which will display the instructions you need to follow to add your servers as nodes and join them to the dokploy manager node. Once you follow the instructions, the workers or managers will appear in the table. **Storage Cleanup Note**: Dokploy does not perform automatic cleanup of storage for workers or other associated nodes that are not the Dokploy server. For automatic cleanup, you can add your node as a remote server and configure cleanups, or create a schedule that performs that cleanup. Additionally, you don't need to perform setup when you only add the node as a remote server. For more information, see the [Remote Servers documentation](/docs/core/remote-servers). # Comparison Comparison of the following deployment tools: | Feature | Dokploy | CapRover | Dokku | Coolify | | --------------------------------------- | ------- | --------------------- | --------------------- | ------- | | **User Interface** | ✅ | ✅ | ❌ | ✅ | | **Docker compose support** | ✅ | ❌ | ❌ | ✅ | | **API/CLI** | ✅ | ✅ | ✅ | ✅ | | **Multi node support** | ✅ | ✅ | ✅ | ✅ | | **Traefik Integration** | ✅ | ✅ | ✅ | ✅ | | **User Permission Management** | ✅ | ❌ | ❌ | ✅ | | **Bitbucket Integration** | ✅ | ❌ | ❌ | ❌ | | **Gitlab Integration** | ✅ | ❌ | ✅ | ❌ | | **Gitea Integration** | ✅ | ❌ | ✅ | ❌ | | **Advanced User Permission Management** | ✅ | ❌ | ❌ | ❌ | | **Terminal Access Built In** | ✅ | ❌ | ❌ | ✅ | | **Database Support** | ✅ | ✅ | Available via Plugins | ✅ | | **Monitoring** | ✅ | ✅ | ❌ | ✅ | | **Backups** | ✅ | Available via Plugins | Available via Plugins | ✅ | | **Open Source** | ✅ | ✅ | ✅ | ✅ | | **Notifications** | ✅ | ❌ | ❌ | ✅ | | **Multi Server Support** | ✅ | ❌ | ✅ | ✅ | | **Open Source Templates** | ✅ | ✅ | ❌ | ✅ | | **Rollbacks** | ✅ | ✅ | ❌ | ✅ | | **Shared Enviroment Variables** | ✅ | ❌ | ❌ | ✅ | | **Environments** | ✅ | ❌ | ❌ | ✅ | | **Schedules Jobs** | ✅ | ❌ | ✅ | ✅ | | **Cloudflare Tunnels** | ✅ | ❌ | Available via Plugins | ✅ | | **Custom Build Server** | ✅ | ❌ | ❌ | ✅ | | **Volume Backups** | ✅ | ❌ | ❌ | ❌ | | **Preview Deployments** | ✅ | ❌ | Via GitHub Action | ✅ | | **Teams** | ✅ | ❌ | ❌ | ✅ | | **Cloud/Paid Version** | ✅ | ✅ | ✅ | ✅ | # Concurrent Builds import { Callout } from "fumadocs-ui/components/callout"; Dokploy processes deployments through a queue that is scoped **per server**. Every server, including the Dokploy server itself, has its own independent concurrency setting that controls how many builds can run at the same time on it. ## How the Queue Works Each server (the local Dokploy server, and every remote/build server) has its own queue partition: * Jobs are grouped by server, so builds on different servers never block each other. * Within a server's queue, up to **N** jobs can run in parallel, where **N** is that server's configured concurrency. * Multiple builds of the **same application or Docker Compose service** are always serialized (FIFO), even if concurrency is greater than 1. This prevents two builds of the same service from colliding (same source directory, same container name, etc). This means increasing concurrency lets **different** applications on the same server build at the same time, it does not parallelize multiple deployments of the same app. ## Default Concurrency By default, every server, the Dokploy server and any remote server, has a concurrency of **1**. This means builds on that server run one at a time. ## Limits Concurrent builds are a self-hosted feature and are configured per server. They are not available on Dokploy Cloud, where build scheduling is managed by the platform. Concurrent builds are fully available in the open-source version — no license required. You can set each server's concurrency to any value between **1** and **100**. ## Configuring Concurrency 1. Go to **Dashboard → Settings → Deployments**. 2. Under **Dokploy Server**, set the concurrency for the local server. 3. Under **Remote Servers**, set the concurrency for each remote or build server individually. Each server's concurrency is configured independently, so you can, for example, keep the Dokploy server at 1 while increasing concurrency on a dedicated [build server](/docs/core/remote-servers/build-server) with more resources. # Deployment Options import { Callout } from "fumadocs-ui/components/callout"; Dokploy gives you three ways to run your applications. All of them use the same deployment engine — the difference is **where your apps run** and how the servers relate to each other. 1. **Dokploy Server**: everything runs on the same machine where the Dokploy UI is installed. 2. **Remote Servers**: independent servers connected via SSH, each running its own apps. 3. **Swarm Nodes (Cluster)**: servers joined to the Dokploy server's Docker Swarm to replicate applications across machines. ## Dokploy Server This is the default. When you install Dokploy, the UI, the builds, and your applications all run on the same server. * **No extra configuration**: deploy immediately after installation. * **Scaling**: vertical — add more CPU and RAM through your VPS provider. * **Best for**: most users. It's the simplest option and the recommended starting point; only move to the other options when a single server is no longer enough. ## Remote Servers [Remote Servers](/docs/core/remote-servers) are independent machines that Dokploy manages over SSH. Each remote server runs its own standalone Docker and its own Traefik instance — they don't form a cluster and don't know about each other. * **Isolation**: each server is independent. If one goes down, apps on other servers are unaffected, and your apps don't compete for resources with the Dokploy UI. * **Two types**: [deployment servers](/docs/core/remote-servers) run your apps, and [build servers](/docs/core/remote-servers/build-server) only build images and push them to a registry. * **Requirements**: SSH access to each server. A Docker registry is only needed if you use build servers. * **Best for**: separating apps per environment, region, or customer; keeping the Dokploy UI on a small server while apps run elsewhere. ## Swarm Nodes (Cluster) The [Cluster](/docs/core/cluster) feature joins additional servers as worker or manager nodes of the Dokploy server's Docker Swarm. Traefik on the manager load-balances traffic to the nodes where your application replicas run. * **Replication**: run multiple replicas of the same application across machines, with load balancing handled by Traefik. * **Requirements**: a Docker registry (images must be pushed so other nodes can pull them) and servers with the same architecture as the Dokploy server. * **Trade-offs**: more setup and operational complexity, and Dokploy does not perform automatic storage cleanup on the extra nodes. * **Best for**: horizontally scaling the same application for high availability. ## Comparison | | Dokploy Server | Remote Servers | Swarm Nodes (Cluster) | | ----------------------------- | ---------------------- | ------------------------ | ----------------------- | | **Where apps run** | Same machine as the UI | Independent servers | Nodes of a shared Swarm | | **Connection** | — | SSH | Swarm join token | | **Docker registry required** | No | Only for build servers | Yes | | **Isolation between servers** | — | High (fully independent) | Low (shared cluster) | | **Replicas across servers** | No | No | Yes | | **Automatic storage cleanup** | Yes | Yes (configurable) | No | | **Setup complexity** | None | Low | High | ## Which one should I choose? * **Start with the Dokploy Server** and scale vertically (more CPU/RAM). It covers the vast majority of use cases with zero extra configuration. * **Use Remote Servers** when you want isolation: production apps separated from the Dokploy UI, different servers per project or region, or a dedicated build server. * **Use Swarm Nodes** only when you need the *same* application replicated across multiple machines with load balancing. These options are not mutually exclusive. A common setup is a small server running only the Dokploy UI, with applications deployed to remote servers. You can also add a Swarm node as a remote server to configure storage cleanups on it. # Cloud vs Self-Hosted import { Callout } from 'fumadocs-ui/components/callout'; Both versions of Dokploy share the same **deployment engine** — same Docker/Traefik integration, same API, same core features. The main difference is operational: **who manages the Dokploy instance itself**. On top of that, there are four editions with different limits and extras, summarized below. ## Editions at a glance Dokploy comes in four editions: **Self-Hosted (OSS)**, **Cloud**, **Enterprise Self-Hosted**, and **Enterprise Cloud**. | | Self-Hosted (OSS) | Cloud | Enterprise Self-Hosted | Enterprise Cloud | | ------------------------------------------------------------------------ | :-----------------: | :----------------: | :-------------------------------------------------: | :----------------: | | **Price** | Free | From $4.50/mo | License ([contact us](https://dokploy.com/contact)) | Custom | | **Control plane** | You manage it | Managed by Dokploy | You manage it | Managed by Dokploy | | **Updates** | Manual | Automatic | Manual | Automatic | | **Core deployments** (apps, databases, Compose, domains, SSL, templates) | ✅ | ✅ | ✅ | ✅ | | **Multi-server / remote servers** | ✅ | ✅ | ✅ | ✅ | | **Basic roles** (Owner, Admin, Member) | ✅ | ✅ | ✅ | ✅ | | **Custom roles** (granular permissions) | ❌ | Plan-dependent | ✅ | ✅ | | **SSO (OIDC / SAML)** | ❌ | ❌ | ✅ | ✅ | | **SCIM provisioning** (automated user lifecycle) | ❌ | ❌ | ✅ | ✅ | | **Application Authentication** (SSO gate for your apps) | ❌ | ❌ | ✅ | ✅ | | **Audit logs** | ❌ | ❌ | ✅ | ✅ | | **Whitelabeling** | ❌ | ❌ | ✅ | ❌ | | **Concurrent builds per server** | ✅ Configurable | Managed | ✅ Configurable | Managed | | **Advanced monitoring dashboard** | Basic monitoring | ✅ | Basic monitoring | ✅ | | **Support** | Community (Discord) | Email & Chat | Priority | Priority with SLA | The core deployment experience is identical in every edition — the differences are in team/enterprise capabilities (SSO, SCIM provisioning, custom roles, audit logs, whitelabeling) and who operates the control plane. [Concurrent builds](/docs/core/concurrent-builds) are included in every self-hosted edition, no license required. ## Enterprise: Cloud vs Self-Hosted There are **two ways to get Enterprise**, and they are not the same thing: * **Enterprise Self-Hosted** — you run your own Dokploy instance and activate a [license key](/docs/core/enterprise/license-keys) issued by the Dokploy team. You keep full control of your infrastructure (including air-gapped setups) and unlock SSO, [SCIM provisioning](/docs/core/enterprise/scim), custom roles, audit logs, [Application Authentication](/docs/core/enterprise/sso/application-authentication), and **whitelabeling**. * **Enterprise Cloud** — the Dokploy team manages the control plane for you with a custom plan. You get the same enterprise capabilities (SSO, SCIM provisioning, custom roles, audit logs, Application Authentication) plus managed uptime, automatic updates, and priority support with SLA. Both Enterprise flavors include **all upcoming Enterprise features**: every new Enterprise capability we release is automatically part of your license or plan, at no extra cost. Key differences between the two Enterprise flavors: | | Enterprise Self-Hosted | Enterprise Cloud | | ---------------------------------- | :--------------------------: | :----------------------------------------: | | **Activation** | License key on your instance | Cloud subscription | | **Control plane uptime & updates** | Your responsibility | Managed by Dokploy | | **Whitelabeling** | ✅ | ❌ (control plane is shared infrastructure) | | **Air-gapped / private networks** | ✅ | ❌ | | **Advanced monitoring dashboard** | Basic monitoring | ✅ | ## What's actually different The differences come down to three things: ### 1. Managed uptime With **Self-Hosted**, you are responsible for keeping the Dokploy instance running. If your server goes down, restarts, or runs out of disk — you need to fix it yourself. With **Cloud**, the Dokploy team manages the uptime of the control plane (the UI, database, and management layer). Your applications still run on your own servers, but the management dashboard is maintained by us. ### 2. Automatic updates With **Self-Hosted**, you update Dokploy manually when new versions are released. With **Cloud**, updates are applied automatically — you're always on the latest version without doing anything. ### 3. Support With **Self-Hosted**, support is community-based (Discord, GitHub issues). With **Cloud**, you get direct support depending on your plan: | Plan | Support level | | -------------- | ------------------------- | | **Hobby** | Community (Discord) | | **Startup** | Email & Chat | | **Enterprise** | Priority support with SLA | ## Architecture Both versions use the same architecture. The only difference is **where** the control plane runs. ### Self-Hosted The Dokploy UI, PostgreSQL, Redis, and your applications all run on the same server(s) that you manage. ``` ┌─────────────────────────────────┐ │ Your Server (you manage) │ │ │ │ Dokploy UI + PostgreSQL + Redis│ │ Traefik (reverse proxy) │ │ ───────────────────────────── │ │ Your Apps & Databases │ └─────────────────────────────────┘ ``` ### Cloud The control plane runs on Dokploy's infrastructure. Your servers only run your workloads. ``` ┌─────────────────┐ ┌──────────────────────┐ │ Dokploy Cloud │ SSH │ Your Server(s) │ │ (managed by us) │────────►│ Apps + Databases │ │ │ │ Traefik │ │ UI, DB, Redis │ └──────────────────────┘ └─────────────────┘ ``` Your **applications keep running independently** even if the Cloud control plane is temporarily unavailable. The control plane is only needed for management operations (deploys, config changes, monitoring dashboard, etc.). ## When to choose what | Choose Self-Hosted if... | Choose Cloud if... | | ----------------------------------------- | --------------------------------------------- | | You want zero cost | You don't want to maintain Dokploy itself | | You want full control over everything | You want automatic updates | | You prefer air-gapped or private networks | You want managed uptime for the control plane | | You're comfortable managing servers | You want direct support (Startup/Enterprise) | ## Cloud Plans If you choose Dokploy Cloud, there are several plans depending on your needs: ### Plan comparison | | Hobby | Startup | Enterprise | Agency | | ---------------------- | :--------------------------: | :---------------------------: | :-------------------------: | :-------------------------: | | **Price** | $4.50/mo per server | $15/mo (3 servers included) | Custom | Custom | | **Additional servers** | $4.50/mo each | $4.50/mo each | Custom | Custom | | **Organizations** | 1 | 3 | Custom | Custom | | **Users** | 1 | Unlimited | Unlimited | Unlimited | | **Environments** | 2 | Unlimited | Unlimited | Unlimited | | **Backups** | 1 per app/database | Unlimited | Unlimited | Unlimited | | **Scheduled jobs** | 1 | Unlimited | Unlimited | Unlimited | | **RBAC** | Basic (Owner, Admin, Member) | Basic (Admin/Developer roles) | Fine-grained + custom roles | Fine-grained + custom roles | | **2FA** | ❌ | ✅ | ✅ | ✅ | | **SSO / SAML** | ❌ | ❌ | ✅ | ✅ | | **SCIM provisioning** | ❌ | ❌ | ✅ | ✅ | | **Audit logs** | ❌ | ❌ | ✅ | ✅ | | **White labeling** | ❌ | ❌ | ✅ | ✅ | | **Support** | Community (Discord) | Email & Chat | Priority with SLA | Partner team | Annual billing saves **20%** on all plans. See the [Pricing](https://dokploy.com/pricing) page for the latest details. ### Which plan do I need? * **Hobby** — You're a solo developer deploying personal projects or small client sites on a single server. * **Startup** — You have a team, need multiple environments (production, staging, dev), and want unlimited backups and scheduled jobs. * **Enterprise** — You need SSO/SAML, SCIM provisioning, audit logs, white labeling, custom roles with fine-grained permissions, and priority support with SLA. * **Agency** — You manage infrastructure for multiple clients and need a tailored partnership. # Features Dokploy provides a comprehensive suite of features designed to simplify and enhance the application deployment process. ## Application Deployment 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 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 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. Custom command, by default we use an internal command to build the docker compose, however you can override it with your own command. Note that the custom command fully replaces the default one (the default command is shown in the UI as a reference, and the command always starts with `docker`). 2. Manage volumes and mounts. ## Database Deployment 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. # Goodies 1. **Ansible Dokploy**: Ansible role to deploy Dokploy [Ansible Role](https://github.com/jacobtipp/ansible-dokploy) 2. **Dokploy Oracle infrastructure**: Deploy Dokploy on Oracle infrastructure [Github](https://github.com/statickidz/dokploy-oci-free) 3. **Dokploy Deploy Action 1**: Automatic Dokploy deployments on Github [Github](https://github.com/benbristow/dokploy-deploy-action) 4. **Dokploy Deploy Action 2**: Automatic Dokploy deployments on Github [Github](https://github.com/jmischler72/dokploy-deploy-action) 5. **Dokploy Deploy Action 3**: Automatic Dokploy deployments on Github (Support both `application` and `compose` deployment) [Github](https://github.com/nhridoy/dokploy-deploy-action) 6. **Dokploy JS Sdk**: Dokploy JS SDK [Github](https://github.com/quiint/dokploy.js) 7. **Templates Collection** : Docker compose collection for Dokploy [Github](https://github.com/benbristow/dokploy-compose-templates) 8. **Dokploy Port Updater**: Dokploy Port Updater [Github](https://github.com/clockradios/dokploy-port-updater) 9. **Dokli TUI**: Dokli TUI [Github](https://github.com/jonykalavera/dokli) 10. **nix-dokploy**: A NixOS module that runs Dokploy using declarative systemd units [Github](https://github.com/el-kurto/nix-dokploy) Want to submit your own? [Submit a PR](https://github.com/Dokploy/website/blob/main/README.md) # Welcome to Dokploy 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](https://www.docker.com/) and the flexibility of [Traefik](https://traefik.io/). {/* */} Logo ## Why Choose Dokploy? * **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 Getting started with Dokploy is straightforward. Follow our guides to install and configure your applications and databases effectively. ## Setting up Please go to get started. # Installation 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) ## Virtual Private Server (VPS) 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 * [Hostinger](https://www.hostinger.com/vps-hosting?ref=dokploy) Get 20% Discount using this referral link: [Referral Link](https://www.hostinger.com/vps-hosting?REFERRALCODE=1SIUMAURICI97) * [AmericanCloud](https://app.americancloud.com/register?ref=dokploy) Receive 20$ credits for free: [Referral Link](https://app.americancloud.com/register?ref=dokploy) * [Teramont](https://teramont.net/dokploy) Get 15% discount for free: [Referral Link](https://teramont.net/?partner_coupon=DOKPLOY\&aff_link=https%3A%2F%2Fbilling.teramont.net%2Faff.php%3Faff%3D53%26url%3Dhttps%3A%2F%2Fteramont.net%2Fdokploy-hosting) * [Hetzner](https://www.hetzner.com/cloud/) Get 20€ credits for free with this referral link: [Referral Link](https://hetzner.cloud/?ref=vou4fhxJ1W2D) * [DigitalOcean](https://www.digitalocean.com/pricing/droplets#basic-droplets) Get 200$ credits for free with this referral link: [Referral Link](https://m.do.co/c/7613f9ec4e85) * [Vultr](https://www.vultr.com/pricing/#cloud-compute) Referral Link: [Referral Link](https://www.vultr.com/?ref=9679828) * [Linode](https://www.linode.com/es/pricing/#compute-shared) * [Scaleway](https://www.scaleway.com/en/pricing/?tags=baremetal,available) * [Google Cloud](https://cloud.google.com/) * [AWS](https://aws.amazon.com/ec2/pricing/) ### Requirements 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. ### Port Requirements Before installing Dokploy, ensure the following ports are available on your server: * **Port 80**: HTTP traffic (used by Traefik) * **Port 443**: HTTPS traffic (used by Traefik) * **Port 3000**: Dokploy web interface **Important:** The installation will fail if any of these ports are already in use. Make sure to stop any services using these ports before running the installation script. ### Docker Dokploy utilizes Docker, so it is essential to have Docker installed on your server. If Docker is not already installed, Dokploy's installation script will install it automatically. Use the following command to install Dokploy:
Dokploy Cloud: Use Dokploy directly without worrying about maintenance or updates. Enjoy a hassle-free experience with Dokploy Cloud. Sign up
```bash curl -sSL https://dokploy.com/install.sh | sh ``` See [Manual Installation](/docs/core/manual-installation) if you want to customize your Dokploy installation. ### Advanced Installation Options The installation script automatically detects and installs the latest stable version from GitHub. However, you can customize the installation using environment variables: #### Install Specific Versions **Install Canary Version (Development):** ```bash export DOKPLOY_VERSION=canary && curl -sSL https://dokploy.com/install.sh | sh ``` **Install Latest Stable:** ```bash export DOKPLOY_VERSION=latest && curl -sSL https://dokploy.com/install.sh | sh ``` **Install a Specific Version:** Every [Dokploy release](https://github.com/Dokploy/dokploy/releases) includes its own `install.sh` as a release asset, which installs exactly that version with the setup it expects. Replace the version tag in the URL with the one you want: ```bash curl -sL https://github.com/Dokploy/dokploy/releases/download/v0.26.6/install.sh | sh ``` Don't use `DOKPLOY_VERSION` to install a specific version — the main script at `dokploy.com/install.sh` always targets the latest release, so its setup may not be compatible with older versions. #### Custom Network Configuration If you need to customize the Docker Swarm network configuration (useful to avoid CIDR conflicts with cloud provider VPCs): ```bash export DOCKER_SWARM_INIT_ARGS="--default-addr-pool 172.20.0.0/16 --default-addr-pool-mask-length 24" curl -sSL https://dokploy.com/install.sh | sh ``` #### Manual Advertise Address If the script cannot detect your server's IP automatically, or you want the Swarm to use a specific interface (e.g. a VPN/WireGuard IP), specify it manually: ```bash curl -sSL https://dokploy.com/install.sh | sudo ADVERTISE_ADDR=192.168.1.100 sh ``` If you run the installer with `sudo`, don't rely on `export ADVERTISE_ADDR=...` from your user shell — `sudo` resets the environment, so the variable never reaches the script and it falls back to auto-detection. Pass the variable inline as shown above, or use `sudo -E sh` to preserve your environment. The same applies to `DOKPLOY_VERSION`, `DOCKER_SWARM_INIT_ARGS`, and `ENDPOINT_MODE`. #### Kernels Without IPVS Support Docker Swarm's default service discovery requires IPVS support in the kernel. Some minimal or appliance-style distributions (e.g. ZimaOS and other Buildroot-based images) ship kernels without it. On those systems, install with DNSRR endpoint mode: ```bash curl -sSL https://dokploy.com/install.sh | sudo ENDPOINT_MODE=dnsrr sh ``` See [Services Can't Reach Each Other (Missing IPVS Kernel Modules)](/docs/core/troubleshooting/networking#services-cant-reach-each-other-missing-ipvs-kernel-modules) for how to detect this situation and its trade-offs. ### Proxmox LXC Support The installation script automatically detects Proxmox LXC containers and applies the necessary configurations (`--endpoint-mode dnsrr`) for compatibility. ### Updating Dokploy To update your Dokploy installation to the latest version: ```bash curl -sSL https://dokploy.com/install.sh | sh -s update ``` **Update to Specific Version:** Use the `install.sh` from that version's [GitHub release](https://github.com/Dokploy/dokploy/releases): ```bash curl -sL https://github.com/Dokploy/dokploy/releases/download/v0.26.6/install.sh | sh -s update ``` ## Completing the Setup 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 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. **Important:** Ensure that your server's firewall allows traffic on port 3000 to access the Dokploy web interface. ### Initial Configuration 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. {" "} ### Secure Your Installation After setting up your admin account, it's crucial to secure your Dokploy installation by enabling HTTPS. To configure a domain with SSL/TLS certificates for your Dokploy panel, please refer to the [Domains](/docs/core/domains) section where you'll find detailed instructions for different SSL configurations including Let's Encrypt, Cloudflare, and custom certificates. ### Disable access via ip:port (Optional but Recommended) To enhance security, it's advisable to restrict access to Dokploy via the server's IP address and port. **Important:** Before disabling IP:port access, make sure you have configured a domain with HTTPS working properly. Otherwise, you will lose access to your Dokploy installation. See the [Domains](/docs/core/domains) section to set this up first. Once you have verified that your domain is working correctly, you can disable IP:port access by running this command on the server: ```bash docker service update --publish-rm "published=3000,target=3000,mode=host" dokploy ``` To further secure your installation, consider reading the [Security recommendations](/docs/core/remote-servers/security#security-recommendations) section. # Interface Overview This page is a visual tour of the Dokploy dashboard. Use it to get familiar with each section of the panel before diving into the feature guides. Click any image to zoom in. ## Home The home dashboard summarizes your organization at a glance: projects, services, recent deployments and their status. ## Projects Projects group your services. Each project can hold applications, databases and Docker Compose services, organized per environment. Inside a project you see every service with its live status: ### Environments Every project supports multiple environments (for example `production` and `staging`), each with its own set of services and shared variables. ## Applications The application view centralizes everything about a deployed app. ### General & Providers Connect GitHub, GitLab, Bitbucket, Gitea, any Git URL, a Docker image, or drop files directly: ### Environment Variables ### Domains Add domains with automatic HTTPS via Let's Encrypt: ### Deployments Every deployment is tracked, with a webhook URL for auto-deploys and full build logs: ### Logs Real-time runtime logs with container selection, search and filters: ### Monitoring Per-service CPU, memory, network and disk metrics: ### Advanced Custom commands, cluster settings, resources, and mounts: ## Databases Deploy PostgreSQL, MySQL, MariaDB, MongoDB and Redis with a few clicks: ### Backups Schedule automatic backups to any S3-compatible destination: ## Docker Compose Deploy multi-service stacks from a Git repository or a raw compose file, with a built-in editor: ## Templates Deploy hundreds of open-source apps with one click: ## Monitoring Server-level metrics: CPU, memory, disk and Docker usage: ## Traefik File System Edit the Traefik configuration directly from the panel: ## Docker & Swarm Inspect containers, images and Swarm nodes: ## Requests Analyze incoming HTTP requests handled by Traefik: ## Schedules Run cron jobs against your services: ## Settings ### Web Server Domain, certificates, and maintenance actions for the Dokploy panel itself: ### Remote Servers Deploy to any VPS over SSH: ### Users Invite team members and manage roles: ### Audit Logs Track every action performed in your organization: ### SSH Keys ### Git Providers ### Registry ### S3 Destinations ### Certificates ### Notifications Connect Slack, Discord, Telegram, email and more: ### AI Configure AI providers to enable AI-assisted features: ## Enterprise ### SSO Configure OIDC/SAML providers and protect deployed applications with forward auth: ### Custom Roles Create roles with granular permissions, starting from presets like Viewer, Developer, Deployer or DevOps: ### Whitelabeling Rebrand your Dokploy instance with your own name, logos and colors: ### License # Manual Installation If you wish to customize the Dokploy installation on your server, you can modify several environment variables: 1. **PORT** - Ideal for avoiding conflicts with other services. 2. **TRAEFIK\_SSL\_PORT** - Set to another port if you want to use a different port for SSL. 3. **TRAEFIK\_PORT** - Set to another port if you want to use a different port for Traefik. 4. **ADVERTISE\_ADDR** - Set to another IP address if you want to use a different IP address for Swarm. 5. **RELEASE\_TAG** - Set to a dokploy docker hub tag(latest, canary, feature, etc) 6. **DATABASE\_URL** - Set to another database url if you want to use a different database. 7. **TZ** - Set to another timezone if you want to use a different timezone. ## Installation Script Here is a Bash script for installing Dokploy on a Linux server. Make sure you run this as root on a Linux environment that is not a container, and ensure ports 80, 443, and 3000 are free. ```bash #!/bin/bash install_dokploy() { if [ "$(id -u)" != "0" ]; then echo "This script must be run as root" >&2 exit 1 fi # check if is Mac OS if [ "$(uname)" = "Darwin" ]; then echo "This script must be run on Linux" >&2 exit 1 fi # check if is running inside a container if [ -f /.dockerenv ]; then echo "This script must be run on Linux" >&2 exit 1 fi # check if something is running on port 80 if ss -tulnp | grep ':80 ' >/dev/null; then echo "Error: something is already running on port 80" >&2 exit 1 fi # check if something is running on port 443 if ss -tulnp | grep ':443 ' >/dev/null; then echo "Error: something is already running on port 443" >&2 exit 1 fi # check if something is running on port 3000 if ss -tulnp | grep ':3000 ' >/dev/null; then echo "Error: something is already running on port 3000" >&2 echo "Dokploy requires port 3000 to be available. Please stop any service using this port." >&2 exit 1 fi command_exists() { command -v "$@" > /dev/null 2>&1 } if command_exists docker; then echo "Docker already installed" else curl -sSL https://get.docker.com | sh fi docker swarm leave --force 2>/dev/null get_ip() { local ip="" # Try IPv4 first # First attempt: ifconfig.io ip=$(curl -4s --connect-timeout 5 https://ifconfig.io 2>/dev/null) # Second attempt: icanhazip.com if [ -z "$ip" ]; then ip=$(curl -4s --connect-timeout 5 https://icanhazip.com 2>/dev/null) fi # Third attempt: ipecho.net if [ -z "$ip" ]; then ip=$(curl -4s --connect-timeout 5 https://ipecho.net/plain 2>/dev/null) fi # If no IPv4, try IPv6 if [ -z "$ip" ]; then # Try IPv6 with ifconfig.io ip=$(curl -6s --connect-timeout 5 https://ifconfig.io 2>/dev/null) # Try IPv6 with icanhazip.com if [ -z "$ip" ]; then ip=$(curl -6s --connect-timeout 5 https://icanhazip.com 2>/dev/null) fi # Try IPv6 with ipecho.net if [ -z "$ip" ]; then ip=$(curl -6s --connect-timeout 5 https://ipecho.net/plain 2>/dev/null) fi fi if [ -z "$ip" ]; then echo "Error: Could not determine server IP address automatically (neither IPv4 nor IPv6)." >&2 echo "Please set the ADVERTISE_ADDR environment variable manually." >&2 echo "Example: export ADVERTISE_ADDR=" >&2 exit 1 fi echo "$ip" } advertise_addr="${ADVERTISE_ADDR:-$(get_ip)}" echo "Using advertise address: $advertise_addr" docker swarm init --advertise-addr $advertise_addr if [ $? -ne 0 ]; then echo "Error: Failed to initialize Docker Swarm" >&2 exit 1 fi echo "Swarm initialized" docker network rm -f dokploy-network 2>/dev/null docker network create --driver overlay --attachable dokploy-network echo "Network created" mkdir -p /etc/dokploy chmod 777 /etc/dokploy # Generate secure random password for Postgres POSTGRES_PASSWORD=$(openssl rand -base64 32 | tr -d "=+/" | cut -c1-32) # Store password as Docker Secret (encrypted and secure) echo "$POSTGRES_PASSWORD" | docker secret create dokploy_postgres_password - 2>/dev/null || true echo "Generated secure database credentials (stored in Docker Secrets)" docker service create \ --name dokploy-postgres \ --constraint 'node.role==manager' \ --network dokploy-network \ --env POSTGRES_USER=dokploy \ --env POSTGRES_DB=dokploy \ --secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \ --env POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ --mount type=volume,source=dokploy-postgres,target=/var/lib/postgresql/data \ postgres:16 # Installation 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 \ --mount type=volume,source=dokploy,target=/root/.docker \ --secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \ --publish published=3000,target=3000,mode=host \ --update-parallelism 1 \ --update-order stop-first \ --constraint 'node.role == manager' \ -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ dokploy/dokploy:latest docker run -d \ --name dokploy-traefik \ --restart always \ -v /etc/dokploy/traefik/traefik.yml:/etc/traefik/traefik.yml \ -v /etc/dokploy/traefik/dynamic:/etc/dokploy/traefik/dynamic \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -p 80:80/tcp \ -p 443:443/tcp \ -p 443:443/udp \ traefik:v3.6.7 docker network connect dokploy-network dokploy-traefik # Optional: Use docker service create instead of docker run # docker service create \ # --name dokploy-traefik \ # --constraint 'node.role==manager' \ # --network dokploy-network \ # --mount type=bind,source=/etc/dokploy/traefik/traefik.yml,target=/etc/traefik/traefik.yml \ # --mount type=bind,source=/etc/dokploy/traefik/dynamic,target=/etc/dokploy/traefik/dynamic \ # --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock,readonly \ # --publish mode=host,published=443,target=443 \ # --publish mode=host,published=80,target=80 \ # --publish mode=host,published=443,target=443,protocol=udp \ # traefik:v3.6.7 GREEN="\033[0;32m" YELLOW="\033[1;33m" BLUE="\033[0;34m" NC="\033[0m" # No Color format_ip_for_url() { local ip="$1" if echo "$ip" | grep -q ':'; then # IPv6 echo "[${ip}]" else # IPv4 echo "${ip}" fi } formatted_addr=$(format_ip_for_url "$advertise_addr") echo "" printf "${GREEN}Congratulations, Dokploy is installed!${NC}\n" printf "${BLUE}Wait 15 seconds for the server to start${NC}\n" printf "${YELLOW}Please go to http://${formatted_addr}:3000${NC}\n\n" } update_dokploy() { echo "Updating Dokploy..." # Pull the latest image docker pull dokploy/dokploy:latest # Update the service docker service update --image dokploy/dokploy:latest dokploy echo "Dokploy has been updated to the latest version." } # Main script execution if [ "$1" = "update" ]; then update_dokploy else install_dokploy fi ``` This script includes checks for common pitfalls, installs Docker if it’s not already installed, initializes a Docker Swarm, creates a network, and then pulls and deploys Dokploy. After the script runs, it provides a success message and instructions for accessing Dokploy. This structured format clearly lays out the prerequisites, steps, and post-installation information, making it user-friendly and accessible for those performing manual installations. ## Customize install #### Customize swarm advertise address The --advertise-addr parameter in the docker swarm init command specifies the IP address or interface that the Docker Swarm manager node should advertise to other nodes in the Swarm. This address is used by other nodes to communicate with the manager. By default, the script auto-detects the server IP address (the installer at `dokploy.com/install.sh` prefers a private RFC1918 address and falls back to the public IP). However, you might need to customize this address based on your network configuration, especially if your server has multiple network interfaces or if you're setting up Swarm in a private network. To customize it, set the `ADVERTISE_ADDR` environment variable when running the script: ```bash curl -sSL https://dokploy.com/install.sh | sudo ADVERTISE_ADDR=192.168.1.100 sh ``` :warning: This IP address should be accessible to all nodes that will join the Swarm. ## Proxmox LXC Considerations If you're installing Dokploy in a Proxmox LXC container, the installation script automatically detects the environment and adds `--endpoint-mode dnsrr` to Docker services for compatibility. For manual installations in LXC, add this flag to your service creation commands: ```bash docker service create \ --name dokploy-postgres \ --endpoint-mode dnsrr \ # ... rest of the configuration ``` **Note:** The `--endpoint-mode dnsrr` flag is required for Docker services to work properly in Proxmox LXC containers due to networking limitations. ## Existing Docker Swarm If you already have a Docker Swarm running on your server, do **not** use the installation script — it forces the node to leave the current swarm (`docker swarm leave --force`) and re-initializes it, which would disrupt your existing services. Instead, run the following steps on a **manager** node. They replicate exactly what the install script does, minus the swarm initialization: ```bash # 1. Create the network docker network create --driver overlay --attachable dokploy-network # 2. Create the config directory mkdir -p /etc/dokploy chmod 777 /etc/dokploy # 3. Create the secrets (Postgres password + auth secret) openssl rand -base64 32 | tr -d "=+/" | cut -c1-32 | docker secret create dokploy_postgres_password - openssl rand -hex 32 | docker secret create dokploy_auth_secret - # 4. Create the Postgres service docker service create \ --name dokploy-postgres \ --constraint 'node.role==manager' \ --network dokploy-network \ --env POSTGRES_USER=dokploy \ --env POSTGRES_DB=dokploy \ --secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \ --env POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ --mount type=volume,source=dokploy-postgres,target=/var/lib/postgresql/data \ postgres:16 # 5. Create the Dokploy service 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 \ --mount type=volume,source=dokploy,target=/root/.docker \ --secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \ --secret source=dokploy_auth_secret,target=/run/secrets/dokploy_auth_secret \ --publish published=3000,target=3000,mode=host \ --update-parallelism 1 \ --update-order stop-first \ --constraint 'node.role == manager' \ -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ -e BETTER_AUTH_SECRET_FILE=/run/secrets/dokploy_auth_secret \ dokploy/dokploy:latest # 6. Create the Traefik container # Dokploy generates the Traefik configuration in /etc/dokploy/traefik # on first boot, so give it a few seconds to start sleep 10 docker run -d \ --name dokploy-traefik \ --restart always \ -v /etc/dokploy/traefik/traefik.yml:/etc/traefik/traefik.yml \ -v /etc/dokploy/traefik/dynamic:/etc/dokploy/traefik/dynamic \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -p 80:80/tcp \ -p 443:443/tcp \ -p 443:443/udp \ traefik:v3.6.7 docker network connect dokploy-network dokploy-traefik ``` Once everything is running, open `http://:3000` to access the Dokploy UI. Ports **80**, **443**, and **3000** must be free. If your existing swarm already runs a reverse proxy bound to 80/443, you will need to free those ports or adjust the published ports of the `dokploy-traefik` container — Dokploy manages its own Traefik instance to route the domains of the applications you deploy. **Using your own Postgres?** You can skip step 4 and point Dokploy to an existing database instead: replace the `POSTGRES_PASSWORD_FILE` env var (and the `dokploy_postgres_password` secret) on the `dokploy` service with `-e DATABASE_URL=postgres://user:password@host:5432/dbname`. By default Dokploy connects to `dokploy-postgres:5432` with user and database `dokploy`; these defaults can also be overridden individually with `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, and `POSTGRES_DB`. ## Setup Dokploy Timezone To setup the timezone of Dokploy, you can use the following command: ```bash docker service update --env-add TZ=America/New_York dokploy ``` ## Manual Upgrade To upgrade Dokploy manually, you can use the following command: ```bash curl -sSL https://dokploy.com/install.sh | sh -s update ``` ### Version-Specific Installation & Updates The installation script automatically detects the latest stable version from GitHub. You can also specify a particular version: **Install a Specific Version (Recommended):** Every [Dokploy release](https://github.com/Dokploy/dokploy/releases) includes its own `install.sh` as a release asset, which installs exactly that version with the setup it expects. Just replace the version tag in the URL with the one you want: ```bash curl -sL https://github.com/Dokploy/dokploy/releases/download/v0.15.0/install.sh | sh ``` This is the recommended way to install older versions of Dokploy. The main script at `dokploy.com/install.sh` always targets the latest release, so its setup may not be compatible with older versions. **Install/Update to Canary (Development):** ```bash export DOKPLOY_VERSION=canary && curl -sSL https://dokploy.com/install.sh | sh ``` **Install/Update to Latest Stable:** ```bash export DOKPLOY_VERSION=latest && curl -sSL https://dokploy.com/install.sh | sh ``` **Auto-detect Latest Stable (Default):** ```bash curl -sSL https://dokploy.com/install.sh | sh ``` Alternatively, you can use `bash -s` for inline version specification: ```bash DOKPLOY_VERSION=canary bash -s < <(curl -sSL https://dokploy.com/install.sh) ``` ### Additional Environment Variables **Custom Docker Swarm Network Configuration:** ```bash export DOCKER_SWARM_INIT_ARGS="--default-addr-pool 172.20.0.0/16 --default-addr-pool-mask-length 24" curl -sSL https://dokploy.com/install.sh | sh ``` **Manual Advertise Address:** ```bash curl -sSL https://dokploy.com/install.sh | sudo ADVERTISE_ADDR=192.168.1.100 sh ``` Note: if you run the installer with `sudo`, pass the variable inline as shown above. Using `export` beforehand won't work because `sudo` resets the environment before executing the script. ## Updating Traefik Manually Dokploy does not update the Traefik container automatically when you upgrade. This is intentional to avoid unexpected downtime for your services. If you need a newer Traefik version (for example, due to a breaking change or security fix), you can update it manually. 1. Remove the existing Traefik container. 2. Create a new container with the desired Traefik image version and the same configuration. 3. Connect the new container to the Dokploy network. Example (replace `v3.6.7` with the version you want): ```bash docker rm -f dokploy-traefik docker run -d \ --name dokploy-traefik \ --restart always \ -v /etc/dokploy/traefik/traefik.yml:/etc/traefik/traefik.yml \ -v /etc/dokploy/traefik/dynamic:/etc/dokploy/traefik/dynamic \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -p 80:80/tcp \ -p 443:443/tcp \ -p 443:443/udp \ traefik:v3.6.7 docker network connect dokploy-network dokploy-traefik ``` **Breaking changes:** Some Traefik versions introduce breaking changes that may not be compatible with the configuration and structure Dokploy uses. Before upgrading, check the [Traefik release notes](https://github.com/traefik/traefik/releases) and [Dokploy releases](https://github.com/Dokploy/dokploy/releases) for any announced breaking changes. Using an incompatible version can cause routing issues (e.g. 404s for applications using domains). # Monitoring ### Prerequisites Before setting up monitoring for your applications and servers, ensure you have completed the server deployment setup. You can verify this by: 1. Navigate to Remote Servers → Select your server → Setup Server 2. Validate that you see a green checkmark in every section ### Configuration Options Once the prerequisites are met, you can access the Monitoring Section where you'll find the following configuration options: #### Refresh Rates * **Server Refresh Rate**: Determines how frequently the server metrics are collected (default: 20 seconds). Lower values provide more accurate metrics but increase server load. * **Container Refresh Rate**: Sets the frequency for container metric collection (default: 20 seconds). Similar to server refresh rate, lower values mean more precise data but higher resource usage. #### Data Management * **Cron Job**: Automated task that cleans old metrics based on the retention period settings. * **Server Retention Days**: Specifies how long metrics data is stored (default: 2 days). * **Port**: The designated port for the metrics server (default: 4500). #### Service Selection * **Include Services**: Choose which services to monitor. Options include: * All services * Specific compose services * Specific applications * Both compose and applications * **Exclude Services**: Specify services to exclude from monitoring using the same options as above. #### Alert Thresholds * **CPU Threshold (%)**: Set the CPU usage percentage that triggers an alert. Set to 0 to disable alerts. * **Memory Threshold (%)**: Set the memory usage percentage that triggers an alert. Set to 0 to disable alerts. #### Security and Integration * **Metrics Token**: Authentication token for metrics requests. You can: * Use the automatically generated token * Generate a new token in the server section * **Metrics Callback URL**: The endpoint that receives metrics data. Default URL is: ``` https://app.dokploy.com/api/trpc/notification.receiveNotification ``` You can use this default or configure your own callback URL. In order to enable just click on `Save Changes` button. ### Notifications If you have configured notifications with Server Threshold properties, metric alerts will be sent to your enabled notification providers, the notifications will sent only if the threshold is exceeded based on the Server itself not individual services. ### Important Security Note **Make sure port 4500 is open on your server** to allow proper communication of monitoring metrics. This is essential for the monitoring system to function correctly. If you have errors like failed to fetch metrics, or no data available, just give it a few minutes and check again, this is normal, the server needs to collect data first. You should see something like this for your server: For your services you should see something like this: This is feature only available on Cloud Version of Dokploy. # Multi-Tenancy import { Callout } from 'fumadocs-ui/components/callout'; Dokploy provides a hierarchical multi-tenancy model that lets you organize your infrastructure cleanly — whether you're a solo developer or managing multiple teams. This guide explains how Organizations, Projects, Environments, and Services work together. ## Resource Hierarchy Dokploy organizes all resources in a four-level hierarchy: ``` ┌─────────────────────────────────────────────────────────────┐ │ ORGANIZATION │ │ The top-level tenant. All users, billing, and settings │ │ belong to an organization. │ │ │ │ ┌────────────────────────┐ ┌────────────────────────┐ │ │ │ PROJECT A │ │ PROJECT B │ │ │ │ │ │ │ │ │ │ ┌──────────────────┐ │ │ ┌──────────────────┐ │ │ │ │ │ Environment: │ │ │ │ Environment: │ │ │ │ │ │ Production │ │ │ │ Production │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌────────────┐ │ │ │ │ ┌────────────┐ │ │ │ │ │ │ │ App (Next) │ │ │ │ │ │ App (Go) │ │ │ │ │ │ │ ├────────────┤ │ │ │ │ ├────────────┤ │ │ │ │ │ │ │ PostgreSQL │ │ │ │ │ │ Redis │ │ │ │ │ │ │ ├────────────┤ │ │ │ │ │ │ │ │ │ │ │ │ │ Redis │ │ │ │ │ └────────────┘ │ │ │ │ │ │ └────────────┘ │ │ │ └──────────────────┘ │ │ │ │ └──────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────┐ │ │ │ │ ┌──────────────────┐ │ │ │ Environment: │ │ │ │ │ │ Environment: │ │ │ │ Staging │ │ │ │ │ │ Staging │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌────────────┐ │ │ │ │ │ │ ┌────────────┐ │ │ │ │ │ App (Go) │ │ │ │ │ │ │ │ App (Next) │ │ │ │ │ │ │ │ │ │ │ │ │ ├────────────┤ │ │ │ │ └────────────┘ │ │ │ │ │ │ │ PostgreSQL │ │ │ │ └──────────────────┘ │ │ │ │ │ └────────────┘ │ │ │ │ │ │ │ └──────────────────┘ │ │ │ │ │ └────────────────────────┘ └────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### How it flows ``` Organization ──► Project ──► Environment ──► Service │ │ │ │ Users & Logical Isolation Apps, Billing grouping layer Databases, of work (prod/stg/dev) Compose ``` ## Organization The **Organization** is the top-level container in Dokploy. Everything — users, projects, servers, settings — belongs to an organization. * Each Dokploy instance starts with **one default organization** created during setup. * The user who installs Dokploy becomes the **Owner** of that organization. * All billing, SSO configuration, and global settings are scoped to the organization. ### Key capabilities | Feature | Description | | ------------------- | ----------------------------------------------------------------------- | | **User Management** | Invite members, assign roles (Owner, Admin, Member, or custom roles) | | **SSO Integration** | Connect Auth0, Azure AD, Keycloak, Okta, or Zitadel (Enterprise) | | **Global Settings** | Manage servers, registries, SSH keys, certificates, and S3 destinations | | **Audit Logs** | Track all actions performed by organization members (Enterprise) | ## Projects A **Project** is a logical grouping of related services. Think of it as a workspace for a specific product, client, or initiative. * Projects live inside an organization. * Each project can contain **multiple environments**. * Projects have their own **shared environment variables** that are inherited by all services within. ### Common project structures ``` # By product ├── Project: "Marketing Website" ├── Project: "Mobile API" └── Project: "Internal Tools" # By client (agencies) ├── Project: "Client: Acme Corp" ├── Project: "Client: Globex Inc" └── Project: "Internal Projects" # By team ├── Project: "Frontend Team" ├── Project: "Backend Team" └── Project: "Data Pipeline" ``` ### Creating a project 1. Go to the **Dashboard**. 2. Click **Create Project**. 3. Enter a name and optional description. Projects are the primary unit for **access control**. You can grant members access to specific projects without exposing the rest of your infrastructure. ## Environments **Environments** provide isolation within a project. They allow you to run the same services in different configurations (production, staging, development) without interference. * Each project starts with a **default environment**. * You can create additional environments as needed. * Environments have their own **shared environment variables** that override project-level variables. * Services in different environments are **completely isolated** from each other. ### Environment use cases | Pattern | Environments | Purpose | | -------------------- | ------------------------------------ | ------------------------------ | | **Standard** | `production`, `staging` | Classic deploy pipeline | | **Feature branches** | `production`, `staging`, `feature-x` | Test features in isolation | | **Regional** | `us-east`, `eu-west`, `ap-south` | Multi-region deployments | | **Per-client** | `client-a`, `client-b` | Client-specific configurations | ### Variable inheritance Environment variables flow downward through the hierarchy with the ability to override at each level: ``` Organization └── Project (shared variables: DATABASE_HOST=db.internal) ├── Environment: Production (override: DATABASE_HOST=db-prod.internal) │ └── Service: API (uses DATABASE_HOST=db-prod.internal) │ └── Environment: Staging (no override) └── Service: API (uses DATABASE_HOST=db.internal) ``` Environment-level variables take precedence over project-level variables. Service-level variables take precedence over both. ## Services **Services** are the actual workloads running inside an environment. Dokploy supports three types of services: ### Service types | Type | Description | Examples | | ------------------ | ------------------------------------------------------- | ------------------------------------------ | | **Application** | Your custom app deployed from Git or Docker | Next.js app, Go API, Python worker | | **Database** | Managed database instances | PostgreSQL, MySQL, MongoDB, Redis, MariaDB | | **Docker Compose** | Multi-container stacks defined via `docker-compose.yml` | WordPress + MySQL, ELK stack | Each service gets its own: * **Domains** — Custom domains with automatic SSL via Traefik * **Environment Variables** — Service-specific configuration * **Deployments** — Independent deploy history and rollbacks * **Logs & Monitoring** — Per-service resource metrics * **Backups** — Automated database backups (for database services) ## Access Control Dokploy's permission system maps directly to this hierarchy, allowing you to control who can see and do what at every level. ### Role hierarchy ``` Owner (full control) │ ├── Admin (full control, cannot manage other admins/owner) │ ├── Member (limited, configurable permissions) │ ├── Can be granted access to specific Projects │ ├── Can be granted access to specific Environments │ └── Permissions are configurable per resource type │ └── Custom Role (Enterprise) └── Fine-grained permissions across 25+ categories ``` ### Permission scoping | Level | What you can control | | ---------------- | ----------------------------------------------------------------- | | **Organization** | Who can manage users, servers, registries, SSH keys, certificates | | **Project** | Who can view/create/delete projects and their services | | **Environment** | Who can access specific environments (e.g., only production) | | **Service** | Who can deploy, view logs, manage environment variables | For detailed permission configuration, see [Permissions](/docs/core/permissions). For enterprise custom roles, see [Custom Roles](/docs/core/enterprise/custom-roles). ## Best Practices ### Naming conventions Use consistent, descriptive names across your hierarchy: ``` Organization: "Acme Corp" └── Project: "acme-ecommerce" ├── Environment: "production" │ ├── Service: "storefront" (Application) │ ├── Service: "api" (Application) │ ├── Service: "postgres-main" (Database) │ └── Service: "redis-cache" (Database) │ └── Environment: "staging" ├── Service: "storefront" ├── Service: "api" └── Service: "postgres-main" ``` ### Separation strategies | Strategy | When to use | Example | | ------------------------------- | -------------------------------------------------- | -------------------------------------- | | **One project per product** | You have distinct products with separate teams | `website`, `mobile-api`, `admin-panel` | | **One project per client** | You're an agency or MSP managing multiple clients | `client-acme`, `client-globex` | | **One environment per stage** | Standard dev → staging → production workflow | `development`, `staging`, `production` | | **One environment per feature** | You want isolated testing of features before merge | `feature-auth-v2`, `feature-payments` | ### Security recommendations 1. **Principle of least privilege** — Only grant the minimum permissions each user needs. 2. **Use environments for isolation** — Never run staging and production services in the same environment. 3. **Scope variables properly** — Put shared secrets at the project level, environment-specific values at the environment level. 4. **Audit regularly** — Review user access and permissions periodically, especially when team members change roles. Use [Audit Logs](/docs/core/enterprise/audit-logs) (Enterprise) to track changes. 5. **Use custom roles** — If the default roles don't fit your needs, create [Custom Roles](/docs/core/enterprise/custom-roles) (Enterprise) with exactly the permissions required. # Patches Patches allow you to apply file-level modifications to your repository during the build process. Patches are applied after cloning the repository and before building, letting you override or add files without modifying the source repository directly. ## Use Cases * Override configuration files for specific environments * Inject environment-specific settings * Modify source code before building * Add files that shouldn't be committed to the repository ## How It Works 1. Navigate to the **Patches** section in your application settings 2. Click **Create Patch** to add a new patch 3. Select a file from the repository tree to edit, or create a new file 4. Make your modifications and click **Save Patch** Patches are applied in order every time a build is triggered, after the repository is cloned and before the build step runs. ## Creating a Patch ### Edit an Existing File 1. Click **Create Patch** 2. Browse the file tree and select the file you want to modify 3. Edit the file content in the editor 4. Click **Save Patch** ### Create a New File 1. Click **Create Patch** 2. Navigate to the desired directory in the file tree 3. Click **New file in root** or navigate to a subdirectory 4. Enter the filename and content 5. Click **Create**, then **Save Patch** ### Delete a File 1. Click **Create Patch** 2. Select the file you want to remove 3. Click **Mark for deletion** 4. Click **Save Patch** Patches do not modify your original repository. They are only applied temporarily during the build process. ## Managing Patches You can view all configured patches in the Patches section. Each patch shows the target file path and the type of operation (edit, create, or delete). You can edit or remove patches at any time. Patches are persistent and will be applied on every build. If you no longer need a patch, make sure to remove it to avoid unintended modifications in future builds. If a patch targets a file that doesn't exist in the repository (for edit operations), the build will fail. Make sure your patches reference valid file paths. # Providers Dokploy offers several deployment methods, streamlining the process whether you're utilizing GitHub, any Git provider, Docker, or automated deployments. 1. GitHub 2. Gitlab 3. Bitbucket 4. Gitea 5. Git 6. Docker (Only Applications) 7. Drag and Drop .zip (Only Applications) 8. Raw (Only Docker Compose) ## GitHub, Gitlab, Bitbucket, Gitea 1. [Github](/docs/core/github) Guide. 2. [Gitlab](/docs/core/gitlab) guide. 3. [Bitbucket](/docs/core/bitbucket) guide. 4. [Gitea](/docs/core/gitea) guide. ## Git For deployments from any Git repository, whether public or private, you can use either SSH or HTTPS: ### Public Repositories (HTTPS) 1. Enter the repository URL in `HTTPS URL`. 2. Type the branch name. 3. Click on `Save`. ### Private Repositories For private repositories, is required to first create an SSH Key The Steps are almost similar for all providers. 1. Go to [SSH Keys Section](/docs/core/ssh-keys) and click on `Create SSH Key`. 2. Click on `Generate RSA SSH Key` and copy the `Public Key`. 3. Go to your Git Provider, either Github, Gitlab, Bitbucket, Gitea or any other. 4. Go to `Settings` and search for `SSH Keys`. 5. Click on `Add SSH Key`. 6. Paste the SSH Key and click on `Add Key`. You can then copy the SSH key and paste it into the settings of your account. This is for Github, but the same applies for Gitlab, Bitbucket, Gitea, etc. This enables you to pull repositories from your private repository, a method consistent across nearly all providers, remember to use the SSH URL `git@github.com:user/repo.git` and not the HTTPS URL `https://github.com/user/repo.git`. ## Docker (Applications) For Docker deployments you have two options: 1. Login to your registry using the [Registry Section](/docs/core/registry) and it automatically will pull the image from the registry in the case of a private registry. 2. Provide the username and password directly in the application settings. ## Drag and Drop .zip (Applications) You can upload a zip file directly from your computer and trigger a deployment. ## Raw (Docker Compose) You specify a docker compose file directly in the code editor and trigger a deployment. Normal # Reset Password & 2FA import { Step, Steps } from 'fumadocs-ui/components/steps'; ## Reset Password To reset your password, follow these steps: Log in to your VPS. Run the command below to get the container ID of the dokploy container. ```bash docker ps ``` Run command below to open a shell in the dokploy container. ```bash docker exec -it bash -c "pnpm run reset-password" ``` It will display a random password. Copy it and use it to access again to the dashboard. ## Reset 2FA To disable 2FA, follow these steps: To reset your 2FA, follow these steps: Log in to your VPS. Run the command below to get the container ID of the dokploy container. ```bash docker ps ``` Run command below to open a shell in the dokploy container. ```bash docker exec -it bash -c "pnpm run reset-2fa" ``` You can now login again without having to supply a 2FA code. # Schedule Jobs Schedule Jobs in Dokploy allows you to create and manage automated tasks that run on a specified schedule using cron expressions. Each job execution creates a log entry where you can monitor the output and execution status. ## Job Types Dokploy supports four types of scheduled jobs: 1. **Application Jobs**: Run commands inside specific application containers 2. **Compose Jobs**: Execute commands in Docker Compose services 3. **Server Jobs**: Run scripts on remote servers (executed on the host) 4. **Dokploy Server Jobs**: Execute tasks at the container level within the Dokploy container. These jobs can interact with commands inside the Dokploy container (e.g., `docker ps`, `docker image prune`), but they are not executed directly on the host system ## Container-based Jobs (Application and Compose) For application and compose jobs, you can run single commands that will be executed inside the target container. Dokploy internally uses Docker exec to run these commands: ```bash docker exec -it ``` ### Example Assuming you with a nginx container and you want to check the nginx version in a container: 1. Create a new schedule job 2. Set the command to: `nginx -v` 3. Configure your desired schedule using cron syntax 4. Save and monitor the execution logs The target container must be running for the job to execute successfully. For docker compose jobs, is required to not change the COMPOSE\_PROJECT\_NAME environment variable, since this is used to identify the project. ## Server-based Jobs (Server and Dokploy Server) ### Server Jobs For remote servers, you can write bash scripts to perform various tasks. These scripts are executed directly on the host system and can use any command or tool available on the target server. ### Dokploy Server Jobs Dokploy Server Jobs are executed at the container level within the Dokploy container. This means: * Commands run inside the Dokploy container environment * You can interact with Docker commands (e.g., `docker ps`, `docker image prune`, `docker system prune`) * Scripts have access to the Docker socket and can manage containers and images * Jobs do not execute directly on the host system, but within the containerized Dokploy environment **Example**: You can create a scheduled job to clean up unused Docker images: ```bash #!/bin/bash docker image prune -af ``` This command will run inside the Dokploy container and can interact with Docker to clean up images. Make sure any required dependencies are installed on the target server before using them in your scripts. ### Example 1: Automatic Docker Cleanup This script cleans up unused Docker containers. You could schedule it to run every 15 minutes using the cron expression `*/15 * * * *`: ```bash #!/bin/bash docker system prune --force ``` ### Example 2: Custom Database Backup You can create scripts to backup databases that aren't natively supported by Dokploy. Here's an example structure for a custom backup script: ```bash #!/bin/bash # Backup script for custom database backup_date=$(date +%Y%m%d_%H%M%S) backup_file="database_${backup_date}.backup" # search the container name container_name=$(docker ps --filter "name=clickhouse" --format "{{.Names}}") # Add your backup commands here docker exec -it $container_name clickhouse-client --query "BACKUP DATABASE mydb TO '/backups/$backup_file'" # Upload to S3 (if needed) # aws s3 cp /backups/$backup_file s3://your-bucket/backups/ ``` ## Best Practices 1. Always test your commands or scripts manually before scheduling them 2. Use appropriate error handling in your scripts 3. Consider the impact of scheduled jobs on system resources # SSH Keys import { Callout } from 'fumadocs-ui/components/callout'; Dokploy provides a section exclusively for SSH keys, allowing you to manage your SSH keys in a centralized location. SSH Keys can be used for two purposes: * **Private Repositories**: You can use SSH Keys, to access to private repositories, this is only for `Git` provider in your application or docker compose. * **Multi Server**: You can use SSH Keys, to access remotely to your servers via SSH. To create a SSH Key, is a very easy process, just click on `Create SSH Key` We offer two SSH Keys Generation types: 1. **RSA Key**: This is the most commonly used key type, and generates a 2048-bit RSA key. 2. **Ed25519 Key**: This is a newer key type that generates a 256-bit Ed25519 key. You can also create or paste your own SSH Key, you can edit the `Private Key` and `Public Key` fields without restrictions, make sure to use the correct format for the key type you are using. Once you create a SSH Key you will not be able to read the `Private Key` anymore. # Uninstall import { Step, Steps } from 'fumadocs-ui/components/steps'; Follow these steps to completely remove Dokploy and its components from your server. Remove the docker swarm services created by Dokploy: ```bash docker service remove dokploy dokploy-traefik dokploy-postgres dokploy-redis docker container remove -f dokploy-traefik ``` Remove the docker volumes created by Dokploy: ```bash docker volume remove -f dokploy dokploy-postgres dokploy-redis ``` Remove the docker network created by Dokploy: ```bash docker network remove -f dokploy-network docker network remove -f ingress ``` If you were running a Cluster, then for each worker node, remove all it's services and make it leave the swarm: ```bash docker service rm $(docker service ls -q) docker system prune -a -f docker swarm leave ``` Make the manager node (where Dokploy is installed) leave the swarm (run it on all manager nodes if you had more than one): ```bash docker swarm leave --force ``` Docker cleanup to remove leftovers: ```bash docker container prune --force docker image prune --all --force docker volume prune --all --force docker builder prune --all --force docker system prune --all --volumes --force ``` Remove the dokploy files and directories from your server: ```bash sudo rm -rf /etc/dokploy ``` # Environment Variables import { Callout } from "fumadocs-ui/components/callout"; ## Overview Environment variables in Dokploy allow you to: * Define configuration once and reuse it * Share values across multiple services * Reference values from within the same service * Centrally manage sensitive information ## Defining Variables You can declare environment variables either: * **Project-level (shared)** — available across all services in the project * **Environment-level** — specific to a single environment * **Service-level** — specific to a single service ## Project-Level Variables ### Practical Example Let's consider a common scenario where you have: * A PostgreSQL database * Two services that need to connect to this database ### 1. Define Shared Variable In the project's shared variables section, define: ```bash DATABASE_URL=postgresql://postgres:postgres@database:5432/postgres ``` ### 2. Use the Variable in Services In each service's environment variables tab, reference the shared variable: ```bash DATABASE_URL=${{project.DATABASE_URL}} ``` Dokploy will automatically replace `${{project.DATABASE_URL}}` with the value defined in the project's shared variables. You can use shared environment variables in all the services available in dokploy. ## Environment-Level Variables ### Practical Example Let's consider a scenario where you have: * A staging environment with different database credentials * Multiple services that need environment-specific configurations ### 1. Define Environment Variable In the environment's variables section, define: ```bash DATABASE_PASSWORD=staging_secret_password API_KEY=staging_api_key_12345 ``` ### 2. Use the Variable in Services In each service's environment variables tab, reference the environment variable: ```bash DATABASE_URL=postgresql://postgres:${{environment.DATABASE_PASSWORD}}@staging-db:5432/postgres EXTERNAL_API_KEY=${{environment.API_KEY}} ``` Dokploy will automatically replace `${{environment.VARIABLE_NAME}}` with the value defined in the environment's variables. You can use environment variables in all the services available in that specific environment. ## Service-Level Variables Service-level variables are specific to a single service and can be used to override shared variables or define service-specific configurations. ### Practical Example Let's say you have a service that requires a different database user. You can define a service-level variable: ```bash DATABASE_USER=service_user DATABASE_PASSWORD=service_password DATABASE_URL=postgresql://${{DATABASE_USER}}:${{DATABASE_PASSWORD}}@service-database:5432/postgres ``` Preview Deployments environments also include a service-level variable called `DOKPLOY_DEPLOY_URL`, which points to the deployment URL of the service. It can be used as `${{DOKPLOY_DEPLOY_URL}}` for variables like `APP_URL=https://${{DOKPLOY_DEPLOY_URL}}`. ## Secrets from External Vaults Besides shared variables, you can reference secrets stored in an external secret manager (HashiCorp Vault/OpenBao, Infisical, AWS Secrets Manager, Doppler, Azure Key Vault): ```bash DB_PASSWORD=${{vault.prod-vault.myapp/prod:DB_PASSWORD}} ``` Values are fetched at deploy time and never stored in Dokploy. See [Secrets Providers](/docs/core/secrets-providers) for setup, reference formats and access control. ### Best Practices * Use shared variables for credentials and configurations that repeat across services * Keep descriptive variable names * Document the purpose of each variable for easier maintenance # Videos import { Card, Cards } from 'fumadocs-ui/components/card'; ## Dokploy Cloud - Introduction