Dokploy Deploy

---
title: Advanced
description: Learn how to use advanced features in your application.
---

This section is designed for experienced users who need to manage complex configurations and orchestration settings in Dokploy. The **Advanced** tab is located in your **Applications** settings. Here, you can execute custom commands, manage cluster replicas, select Docker registries, and configure Docker Swarm settings.

### Run Command

- **Purpose**: Allows users to execute custom shell commands directly within the container.
- **Usage**: Enter the command you need to run in the provided field and click 'Save' to execute it within the container environment. This tool is particularly useful for debugging or specific administrative tasks.

### Cluster Settings

- **Purpose**: Manages the scaling and distribution of the application across multiple servers or nodes.
- **Replicas**: Set the number of instances of your **application** that should be running.
- **Registry Selection**: Choose the Docker registry from which your container images will be pulled. This is crucial for ensuring that the correct images are used during deployment.

#### Important Note
Always click 'Redeploy' after modifying the cluster settings to apply the changes.

### Swarm Settings

Swarm settings allow for detailed configuration of how containers are orchestrated within the Docker Swarm.

#### Health Check

- **Purpose**: Ensures that containers are running smoothly and restarts them if they fail.
- **Configuration**: Specify parameters like test commands, intervals, timeouts, start periods, and retries.

#### Restart Policy

Defines how containers should be handled if they exit or fail, the configuration is as follows:

- **Condition**: Specifies under what condition a restart should occur.
- **Delay**: Sets the time delay between restarts.
- **Max Attempts**: Limits the number of restart attempts.
- **Window**: Defines the time window used to evaluate the restart policy.

#### Update Config

Manages the deployment and update process of services in the swarm, the configuration is as follows:


- **Parallelism**: Number of containers to update simultaneously.
- **Delay**: Time between updates.
- **Failure Action**: Action to take if an update fails.
- **Monitor**: Duration to monitor a container after an update.
- **Max Failure Ratio**: The fraction of containers that are allowed to fail before the update is considered a failure.
- **Order**: The order in which containers are stopped and started during an update.

#### Placement

Controls where containers are placed within the swarm based on specific rules and preferences, the configuration is as follows:

- **Constraints**: Conditions that must be met for a container to be placed on a node.
- **Preferences**: Preferences for placing containers across nodes to spread load evenly.

### Rollback Config

Manages the rollback process for services when updates fail, the configuration is as follows:

- **Parallelism**: Number of containers to rollback simultaneously.
- **Delay**: Time between rollbacks.
- **FailureAction**: Action to take if a rollback fails.
- **Monitor**: Duration to monitor a container after a rollback.
- **MaxFailureRatio**: The fraction of containers that are allowed to fail before the rollback is considered a failure.
- **Order**: The order in which containers are stopped and restarted during a rollback.

### Mode

Defines how services are replicated within the swarm, the configuration is as follows:

- **Replicated**: Services are replicated across nodes as specified.
- **Replicas**: Number of replicas per service.
- **Global**: A single instance of the service runs on every node.
- **ReplicatedJob**: Runs a job in a replicated manner.
- **MaxConcurrent**: Maximum number of jobs running concurrently.
- **TotalCompletions**: Total number of times the jobs need to complete.

### Network

Configures network settings for the services, the configuration is as follows:

- **Target**: Specifies the network name.
- **Aliases**: Provides aliases for the network.
- **DriverOpts**: Network driver options like MTU size and host binding.

### Labels

Assigns metadata to containers to help identify and organize them, the configuration is as follows:

- **Labels**: Key-value pairs assigned to the service. For example:
1. `com.example.app.name`: "my-app"
2. `com.example.app.version`: "1.0.0"


### Note
Modifying Swarm Settings requires careful consideration as incorrect configurations can disrupt the entire container orchestration. Always ensure you understand the implications of the changes you are making.


## Build Server

You can configure your application to use an external build server to compile and build your application. This feature allows you to separate the build process from your deployment servers, which is particularly useful when you want to:

- Use powerful build resources without paying for expensive deployment servers
- Keep your deployment servers lightweight
- Build once and deploy to multiple servers
- Isolate the build process from production environments

When you enable a custom build server:

1. **Build Phase**: Dokploy connects to your build server via SSH, clones your repository, and builds the Docker image on the build server
2. **Push Phase**: The built image is pushed to your configured Docker registry
3. **Deploy Phase**: Your deployment server(s) pull the image from the registry and deploy it

<Callout type="info">
  **Important**: Build servers are currently **only available for Applications**. This feature is not supported for Docker Compose deployments.
</Callout>

<Callout type="warn">
  **Required Configuration**: When using a build server, you must configure a Docker registry in your Dokploy settings. The built image needs to be stored in a registry that's accessible to your deployment servers. See [Docker Registry](/docs/core/registry) for configuration details.
</Callout>

**For complete setup instructions, configuration details, and best practices, please read the comprehensive [Build Server guide](/docs/core/remote-servers/build-server).**

## Resources

Manage the memory and CPU resources allocated to your applications or databases. These settings help control resource consumption and ensure fair distribution across your containers.

<Callout type="info">
  Remember to click **Redeploy** after modifying the resources to apply the changes.
</Callout>

### Memory Resources

Docker API expects memory values in **bytes**. Dokploy provides a user-friendly interface that accepts values with units and converts them automatically.

#### Memory Limit

The maximum amount of memory the container can use. If the container tries to use more memory than this limit, it will be killed by the Docker daemon.

**Format**: Enter a number followed by the unit (B, KB, MB, GB)

**Docker API Value**: The value is converted to bytes internally
- `1073741824` bytes = 1GB
- `268435456` bytes = 256MB
- `536870912` bytes = 512MB

**Examples**:
- `256MB` → Limits container to 256 megabytes
- `1GB` → Limits container to 1 gigabyte
- `2GB` → Limits container to 2 gigabytes

#### Memory Reservation

The minimum amount of memory guaranteed to the container. Docker will try to ensure this amount is always available, but the container can use more if available.

**Format**: Enter a number followed by the unit (B, KB, MB, GB)

**Docker API Value**: The value is converted to bytes internally
- `268435456` bytes = 256MB
- `536870912` bytes = 512MB

**Examples**:
- `128MB` → Reserves at least 128 megabytes
- `256MB` → Reserves at least 256 megabytes
- `512MB` → Reserves at least 512 megabytes

<Callout type="warn">
  Memory Reservation should always be **less than or equal to** Memory Limit. If you set a reservation higher than the limit, Docker will use the limit value.
</Callout>

### CPU Resources

Docker API expects CPU values in **nanoseconds** (for periods) or as a decimal fraction of available CPU cores. Dokploy displays this in a user-friendly format.

#### CPU Limit

The maximum number of CPU cores the container can use. This is a hard limit enforced by the Docker daemon.

**Format**: Enter as a decimal number representing CPU cores
- `2000000000` nanoseconds = 2 CPUs (2 full cores)
- `1000000000` nanoseconds = 1 CPU (1 full core)
- `500000000` nanoseconds = 0.5 CPU (half a core)

**Docker API Value**: Internally represented as `NanoCPUs`

**Examples**:
- `1 CPU` → Limits to 1 full CPU core (1000000000 nanoseconds)
- `2 CPUs` → Limits to 2 full CPU cores (2000000000 nanoseconds)
- `0.5 CPU` → Limits to half a CPU core (500000000 nanoseconds)
- `4 CPUs` → Limits to 4 full CPU cores (4000000000 nanoseconds)

#### CPU Reservation

The minimum number of CPU cores reserved for the container. Docker will try to ensure this amount is always available.

**Format**: Enter as a decimal number representing CPU cores
- `1000000000` nanoseconds = 1 CPU
- `500000000` nanoseconds = 0.5 CPU

**Docker API Value**: Internally represented as `NanoCPUs`

**Examples**:
- `0.5 CPU` → Reserves half a CPU core (500000000 nanoseconds)
- `1 CPU` → Reserves 1 full CPU core (1000000000 nanoseconds)
- `0.25 CPU` → Reserves a quarter CPU core (250000000 nanoseconds)

<Callout type="warn">
  CPU Reservation should always be **less than or equal to** CPU Limit. Setting it too high may prevent the container from starting if resources aren't available.
</Callout>



#### Docker API Reference

When Dokploy communicates with Docker API, these values are sent in the service specification:

```json
{
  "TaskTemplate": {
    "Resources": {
      "Limits": {
        "NanoCPUs": 2000000000,
        "MemoryBytes": 1073741824
      },
      "Reservations": {
        "NanoCPUs": 1000000000,
        "MemoryBytes": 536870912
      }
    }
  }
}
```

This JSON represents:
- **CPU Limit**: 2 CPUs (2000000000 nanoseconds)
- **Memory Limit**: 1GB (1073741824 bytes)
- **CPU Reservation**: 1 CPU (1000000000 nanoseconds)
- **Memory Reservation**: 512MB (536870912 bytes)

#### Learn More

For detailed information about Docker API resource specifications and service creation, refer to the official Docker Engine API documentation:

[Docker Engine API - Service Create](https://docs.docker.com/reference/api/engine/version/v1.51/#tag/Service/operation/ServiceCreate)

This documentation includes:
- Complete resource specification schema
- Advanced configuration options
- API request/response examples
- Additional parameters and constraints


### Volumes/Mounts

Configure persistent storage for your application to ensure data remains intact across container restarts and deployments.


**Bind Mount**: Maps a host file or directory to a container file or directory. Typically used for specific configurations or databases.
1. **Host Path**: Path on the host.
2. **Mount Path**: Path in the container.

**Volume Mount**: Uses Docker-managed volumes that are easier to back up and migrate than bind mounts.
1. **Volume Name**: Name of the Docker-managed volume.
2. **Mount Path**: Path in the container where the volume is mounted.

**File Mount**: Specifically for single files, useful for configuration files.
1. **Content**: The content to store in the file.
2. **File Path**: The name of the file.
3. **Mount Path**: Path in the container where the file is placed. **The path must also contain the filename.**

File mounts are a Dokploy feature. When you create a file mount, Dokploy stores the file in a folder called `files` inside your project directory. This file is created once when you set up the file mount and persists across deployments.

<ImageZoom src="/assets/file-mount-configuration.webp" width={800} height={630} className="rounded-lg"/>

<ImageZoom src="/assets/file-mount.png" width={800} height={630} className="rounded-lg"/>

### Redirects

Redirect requests to your application to another URL based on specified rules, enhancing navigational efficiency and SEO.

- **Regex**: Enter a regular expression to match the URLs that need redirecting.
- **Replacement**: Specify the target URL where traffic should be redirected.
- **Permanent**: Toggle this option to apply a permanent (HTTP 301) redirection, indicating to browsers and search engines that the page has moved permanently.

#### Example
To redirect all traffic from "http://localhost" to "http://mydomain", set the Regex as `http://localhost/(.*)` and the Replacement as `http://mydomain/$1`.


### Security

Add basic authentication to your application to restrict access.

- **Username**: Enter a username.
- **Password**: Enter a password.

#### Important Note
Adding basic authentication will prompt users for a username and password before allowing access to the application. Use this for environments where an additional layer of security is required.


### Ports

Expose your application to the internet by configuring network ports, allowing external access.

- **Published Port**: The port number on the host that will route traffic to your application.
- **Target Port**: The port number inside the container that the application uses.
- **Protocol**: Choose between TCP and UDP based on your application's requirements.

#### Important Note
Ensure that the published port does not conflict with other services on the host to avoid port binding errors, also this port is used mostly for accesing the application from the outside, eg your-ip:port, this is not for accessing the application trought a domain.

### Traefik

Provides a dynamic and robust method to manage HTTP traffic to your services, including load balancing and SSL termination.

- **Rules**: Define complex routing, load balancing, and security configurations using Traefik's powerful rule-based configuration system.

---
title: Build Type
description: "Learn about the different build types available in Dokploy, including Nixpacks, Dockerfile, and Buildpack options."

---

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


Dokploy offers three distinct build types for deploying applications, each suited to different development needs and preferences.

### Nixpacks

This is the default build type in Dokploy. When you select Nixpacks, Dokploy builds your application as a Nixpack, which is optimized for ease of use and efficiency.

Nixpacks expose multiples variables to be configured via environment variables. All of these variables are prefixed with `NIXPACKS_`, you can define them in the `Environment Variables` tab.

| Variable                      | Description                                                                                  |
| :---------------------------- | :------------------------------------------------------------------------------------------- |
| `NIXPACKS_INSTALL_CMD`        | Override the install command to use                                                          |
| `NIXPACKS_BUILD_CMD`          | Override the build command to use                                                            |
| `NIXPACKS_START_CMD`          | Override command to run when starting the container                                          |
| `NIXPACKS_PKGS`               | Add additional [Nix packages](https://search.nixos.org/packages?channel=unstable) to install |
| `NIXPACKS_APT_PKGS`           | Add additional Apt packages to install (comma delimited)                                     |
| `NIXPACKS_LIBS`               | Add additional Nix libraries to make available                                               |
| `NIXPACKS_INSTALL_CACHE_DIRS` | Add additional directories to cache during the install phase                                 |
| `NIXPACKS_BUILD_CACHE_DIRS`   | Add additional directories to cache during the build phase                                   |
| `NIXPACKS_NO_CACHE`           | Disable caching for the build                                                                |
| `NIXPACKS_CONFIG_FILE`        | Location of the Nixpacks configuration file relative to the root of the app                  |
| `NIXPACKS_DEBIAN`             | Enable Debian base image, used for supporting OpenSSL 1.1                                    |

If you need more manage about nixpacks process, you can create a `nixpacks.toml` file in the root of your application you can read here [Nixpacks Configuration](https://nixpacks.com/docs/configuration/file).

Nixpacks support monorepo such as NX Monorepo, Turborepo, Moon Repo, you can read more about it [here](https://nixpacks.com/docs/providers/node#build).

You can read more about Nixpacks [here](https://nixpacks.com/).

Since Nixpacks have a [static builder](https://nixpacks.com/docs/providers/staticfile) Dokploy expose a field called `Publish Directory`  where basically you can specify
the directory that you want to publish after the build process is finished, example:

Astro applications after you build it usually create a `dist` directory, so you can specify the `dist` directory as the publish directory and then Dokploy will
copy all the files in the `dist` directory to the root of your application, and will use a NGINX Optimized Dockerfile to run your application.


### Railpack (NEW)

Railpack is a new build type optimized and is the successor of Nixpacks.

Railpack exposes multiple Build Variables, you can define them in the `Environment Variables` tab.

| Name                  | Description                                                                                                |
| :-------------------- | :--------------------------------------------------------------------------------------------------------- |
| `RAILPACK_BUILD_CMD`           | Set the command to run for the build step. This overwrites any commands that come from providers           |
| `RAILPACK_START_CMD`           | Set the command to run when the container starts                                                           |
| `RAILPACK_PACKAGES`            | Install additional Mise packages. In the format `pkg@version`. The latest version is used if not provided. |
| `RAILPACK_BUILD_APT_PACKAGES`  | Install additional Apt packages during build                                                               |
| `RAILPACK_DEPLOY_APT_PACKAGES` | Install additional Apt packages in the final image                                                         |

### Specifying Railpack Version

Dokploy provides a **Railpack Version** field in the application settings where you can specify a specific version of Railpack to use. This allows you to:

- **Pin to a specific version**: Ensure consistent builds across deployments
- **Use a newer version**: Test or use features from a specific release
- **Stay on a stable version**: Avoid potential issues from automatic updates

**How to use:**

1. Navigate to your application settings
2. Find the **Railpack Version** field
3. Enter the version you want to use (e.g., `0.15.1`)
4. Dokploy will automatically download and use the specified version for your builds

**Example:**

To use Railpack version `0.15.1`, simply enter `0.15.1` in the Railpack Version field.

<Callout type="warn">
  If you specify an invalid version, Dokploy will show an error. Make sure to use a valid version from the [Railpack releases page](https://github.com/railwayapp/railpack/releases).
</Callout>

You can read more about Railpack [here](https://railpack.com/config/environment-variables).

Railpack supports Nodejs, Python, Go, PHP, Go, StaticFile, Shell Scripts.

### Dockerfile

If your project includes a Dockerfile, you can specify its path. Dokploy will use this Dockerfile to build your application directly, giving you full control over the build environment and dependencies

Dokploy expose 3 Fields to be configured:

- `Dockerfile Path (Required)`: The path to the Dockerfile to use for building the application, eg. If your Dockerfile is in the root of your application you can just specify the `Dockerfile` file.
- `Docker Context Path`: This is where the Dockerfile is located, eg. If your Dockerfile is in the root of your application you can just specify the `.` (dot) character, is basically to tell docker what context will use to build your application, you can read [Dockerfile Context](https://docs.docker.com/build/concepts/context/) for more information.
- `Docker Build Stage`: This is the build stage to use for building the application, eg. If you want to use the `builder` stage you can specify the `builder` stage, read more about build stages [here](https://docs.docker.com/build/building/multi-stage/).

#### Environment Variables for Dockerfile Builds

When you enable the Dockerfile build type, two additional fields become available in the **Environment** tab:

- **Build Time Arguments**: Configure [build arguments (ARG)](https://docs.docker.com/build/building/variables/) that are passed to your Dockerfile during the build process. Build arguments allow you to parameterize your Dockerfile, making it more flexible and reusable. For example, you can specify versions of dependencies, feature flags, or other build-time configurations.

- **Build-time Secrets**: Configure [build secrets](https://docs.docker.com/build/building/secrets/) to securely pass sensitive information (such as API tokens, passwords, or SSH keys) to your build process. Unlike build arguments, secrets are not exposed in the final image or build history, making them the recommended way to handle sensitive data during builds.

<Callout type="info">
  Build arguments and environment variables are inappropriate for passing secrets, as they persist in the final image. Always use build-time secrets for sensitive information like API tokens or passwords.
</Callout>



### Buildpack

Dokploy supports two types of buildpacks:

- **Heroku**: Adapted from Heroku's popular cloud platform, these buildpacks are designed for compatibility and ease of migration, you can optional specify the Heroku Version to use, by default Dokploy will use the 24.
- **Paketo**: Provides cloud-native buildpacks that leverage modern standards and practices for building applications.

By choosing the appropriate build type, you can tailor the deployment process to best fit your application's requirements and your operational preferences.


### Static

Static build type is used to server static applications, it will use a NGINX Optimized Dockerfile to run your application.

Dokploy will copy everything from the `Root` directory and will mount it to the `/usr/share/nginx/html` directory, and will use a NGINX Optimized Dockerfile to run your application.

<Callout type="info">
Ensure to use the port `80` when creating a domain.
</Callout>

## Recomendations 

- For prototyping and development purposes, we recommend using the `Nixpacks` build type.
- For production purposes, we recommend follow this [Production Guide](/docs/core/applications/going-production) to have a rock solid deployment.
- For static applications, we recommend using the `Static` build type.

---
title: Going Production
description: Learn how to deploy your application in production in Dokploy.
---

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

By default, dokploy offer multiple [Builds Types](/docs/core/applications/build-type) to deploy your application, the most common is `nixpacks` and `heroku buildpacks`
however this also comes with problems, first is the resources that are required to build your application which some times can lead to timeout on your server or even freezeing your server
and all your application will be down for this reasson, this is mainly problem from `Docker` since the comsumption of resources such as RAM, CPU is very high to build an application.



## Solution

You have two options to solve this problem:

1. Increase the resources of your server CPU, RAM, Disk (Probably is not a good idea and cheapest solution)
2. Build & Publish the application in a CI/CD pipeline eg. Github Actions, Gitlab CI, Gitea Actions, etc. (Recommended)


### Build & Publish the application in a CI/CD pipeline

We will use Github Actions as an example, but you can use any CI/CD pipeline that you want.

We will use the following configuration:

1. **Use Git Provider in Your Application**:
   - Repository: `https://github.com/Dokploy/production-example`
   - Branch: `main`
   - Build path: `/`

<Callout type="info">
The repo have everything you need, however you can follow the same idea for your own applications.

</Callout>


2. The repository already have a Dockerfile, so we will use that, in the case your application is different create your own Dockerfile is required for this guide.
3. We will use `Dockerhub` as an example, but you can use any container registry that you want.
4. Make sure to create the repository in the `Dockerhub` , `namespace` is your username and `repository` is `example`.
5. Create a new Github Actions workflow in `.github/workflows/deploy.yml`
6. Add the following code to the workflow:

```yaml
name: Build Docker images

on:
  push:
    branches: ["main"]

jobs:
  build-and-push-dockerfile-image:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Log in to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }} # Make sure to add the secrets in your repository in -> Settings -> Secrets (Actions) -> New repository secret
          password: ${{ secrets.DOCKERHUB_TOKEN }}   # Make sure to add the secrets in your repository in -> Settings -> Secrets (Actions) -> New repository secret

      - name: Build and push Docker image
        uses: docker/build-push-action@v4
        with:
          context: .
          file: ./Dockerfile
          push: true
          # Make sure to replace with your own namespace and repository
          tags: |
            namespace/example:latest 
          platforms: linux/amd64     
```
7. Create your own Dockerfile, in this case we will use the `Dockerfile` from the repository.

```properties
FROM node:18-alpine AS base
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable

FROM base AS build
WORKDIR /app
COPY . .
COPY package.json pnpm-lock.yaml ./
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
ENV NODE_ENV=production
RUN pnpm run build

FROM base AS dokploy
WORKDIR /app
ENV NODE_ENV=production

# Copy only the necessary files
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./package.json
COPY --from=build /app/node_modules ./node_modules

EXPOSE 3000
CMD ["pnpm", "start"]
```

8. Now when you make a commit to your repository, the workflow will be triggered and the application will build and push to `Dockerhub`.
9. Now let's create application in Dokploy.
10. In `Source Type` select `Docker`
11. In the docker image field enter `namespace/example:latest`
12. Click on `Save`.
13. Click on `Deploy`.
14. Go to `Domains` and click `Dices` icon to generate a domain and the port set to `3000`.
15. Now you can access your application.

### Auto deploy

When using Dockerhub as a registry you can also enable auto deploy, this will automatically deploy your application whenever you push to your repository.

To setup auto deploys for Dockerhub, follow the steps below:

1. Go to your application and select `Deployments` tab.
2. Copy the `Webhook URL`.
3. Go to your Dockerhub repository and select `Webhooks` tab.
4. Set a name for the webhook and paste the `Webhook URL` copied in step 2.
5. That's it, now every time you push to your repository, your application will trigger a deployment in dokploy.

The deployment will trigger only if the `Tag` matches the one specified in Dokploy.


#### External Registry

If you have a registry that is not Dockerhub, you can trigger a deployment after pushing to your repository in Github Actions.

Your workflow will look like this:

This method use the [Api Method](/docs/core/auto-deploy#api-method) to trigger a deployment.

```yaml
name: Build Docker images

on:
  push:
    branches: ["main"]

jobs:
  build-and-push-dockerfile-image:
    runs-on: ubuntu-latest

    steps:
       ...Same as step 7 from the previous example
          
      - name: Trigger Dokploy Deployment
        uses: dokploy/dokploy-action@v1
        run: |
            curl -X 'POST' \
            'https://<your-dokploy-domain>/api/application.deploy' \
            -H 'accept: application/json' \
            -H 'x-api-key: YOUR-GENERATED-API-KEY' \
            -H 'Content-Type: application/json' \
            -d '{
                 "applicationId": "YOUR-APPLICATION-ID"
            }'
```

You can also use this Github Action [Action](https://github.com/marketplace/actions/dokploy-deployment) to automate the deployment.

## Healthcheck & Rollbacks

When using Dokploy you can also configure healthchecks and rollbacks, this will allow you to configure your application to be able to recover from failures.
 
In the repo we are using from the `Step 1.` we have a healthcheck endpoint `/health` that returns a 200 status code and running in the port 3000.

Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings`

There are a couple options that you can use, in this case we will focus on `Health Check` and `Update Config`.

Make sure the API Route exists in your application

```json
{
  "Test": [
    "CMD",
    "curl",
    "-f",
    "http://localhost:3000/health"
  ],
  "Interval": 30000000000,
  "Timeout": 10000000000,
  "StartPeriod": 30000000000,
  "Retries": 3
}
```

Now in the `Update Config`

Now when the application is getting unhealthy response from the health check, the container will rollback to the previous version.

Paste the following code:
```json
{
  "Parallelism": 1,
  "Delay": 10000000000,
  "FailureAction": "rollback",
  "Order": "start-first"
}
```


Now you everything a production ready application with automated deployments, zero downtime, rollbacks and healthchecks.

We recommend strongly to use this approach in production since this will make your server never build the application, will only in charge of the deployment keeping your server without any downtime.

---
title: Applications
description: "Explore the multiple deployment methods available in Dokploy, including GitHub, Git, Docker, and automated deployments via webhooks."
---

Applications in Dokploy are treated as a single service, entity or container, making it easy and intuitive for users to work with each application in its own workspace.

We offer multiple functionalities that you can use to manage your applications, such as:

## General

Configure the source of your code, the way your application is built, and also manage actions like deploying, updating, and deleting your application, and stopping it.

## Environment

If you need to assign environment variables to your application, you can do so here.

In case you need to use a multiline variable, you can wrap it in double quotes just like this `'"here_is_my_private_key"'`.

## Monitoring

Four graphs will be displayed for the use of memory, CPU, disk, and network. Note that the information is only updated if you are viewing the current page, otherwise it will not be updated.

## Logs

If you want to see any important logs from your application that is running, you can do so here and determine if your application is displaying any errors or not.

## Deployments

You can view the last 10 deployments of your application. When you deploy your application in real time, a new deployment record will be created and it will gradually show you how your application is being built.

We also offer a button to cancel deployments that are in queue. Note that those in progress cannot be canceled.

We provide a webhook so that you can trigger your own deployments by pushing to your GitHub, Gitea, GitLab, Bitbucket, DockerHub repository.

## Domains

This is where you will assign your domain so that your application can be accessed from the internet.

There are two ways to assign a domain:

1. Create a custom domain.
2. Use a generated domain, we use traefik.me to generate free domains.

## Advanced Settings

This section provides advanced configuration options for experienced users. It includes tools for custom commands within the container, managing Docker Swarm settings, and adjusting cluster settings such as replicas and registry selection. These tools are typically not required for standard application deployment and are intended for complex management and troubleshooting tasks.

- **Run Command**: Execute custom commands directly in the container, after the application has been build & running.
- **Cluster Settings**: Configure the number of replicas and select the Docker registry for your deployment to manage how your application scales and where it pulls images from.
- **Swarm Settings**: Access additional Docker Swarm configurations for detailed orchestration and scaling across multiple nodes.
- **Resources**: Adjust the CPU and memory allocation for your application.
- **Volumes**: To ensure data persistence across deployments, configure storage volumes for your application, you can create Volumes, Binds, File Mounts.
- **Ports**: Expose your application to the internet by configuring network ports.
- **Traefik**: Modify Traefik settings to manage HTTP request handling for your application.

## Keyboard Shortcuts

To help speed up navigating there are some built in keyboard shortcuts for
navigating tabs on application pages. Similar to GitHub these are all prefixed
with the `g` key so to use them press `g` and then the shortcut key.

| Key | Tab                 |
| --- | ------------------- |
| `g` | General             |
| `e` | Environment         |
| `u` | Domains             |
| `p` | Preview Deployments |
| `s` | Schedules           |
| `v` | Volume Backups      |
| `d` | Deployments         |
| `l` | Logs                |
| `m` | Monitoring          |
| `a` | Advanced            |

### Note

Adjust these settings carefully as incorrect configurations can significantly impact your application’s functionality and availability.

{
	"title": "Applications",
	"pages": [
		"advanced",
		"build-type",
		"preview-deployments",
		"rollbacks",
		"zero-downtime",
		"going-production"
	]
}

---
title: Preview Deployments
description: "Preview deployments allow you to test and review your application changes in an isolated environment before merging to production."
---

Preview deployments are a powerful feature specifically designed for applications with GitHub integration. This feature is disabled by default but can be easily enabled to enhance your development workflow.

<ImageZoom src="/assets/images/preview-deployments.png" width={800} height={630} alt='Preview deployments' className="rounded-lg" />

<Callout type="info">
We recommend not using preview deployments for public repositories, since external people can execute builds and deployments in your server.
</Callout>

## Configuration

By default, Dokploy generates dynamic domains using traefik.me domains, which are free and require no additional configuration. The default port is 3000, but you can adjust this based on your application's requirements. You can also limit the number of  preview deployments per application (default is 3).

### Custom Domains

If you prefer using a custom domain, you can configure it like this:

```
*.mydomain.com
```

Dokploy will generate domains following this pattern:

```
preview-${appName}-${uniqueId}.traefik.me
```

To make this work, you need to point your wildcard DNS record (*) to your server's IP address.

<Callout type="info">
**Hint:** If you need to reference the generated domain in the preview deployment's environment variables, you can do so utilising `${{DOKPLOY_DEPLOY_URL}}`. See [variables documentation](/docs/core/variables#service-level-variables) for more information.
</Callout>

## How It Works

Once enabled, preview deployments are automatically created whenever a pull request is opened against your target branch (configured in your provider settings).

For example:
- If your provider is configured to use the `main` branch
- And you create a pull request from `feature/new-feature` to `main`
- A preview deployment will be automatically created for the `feature/new-feature` branch

Note: Pull requests to branches other than your configured target branch will not trigger preview deployments.

### Filtering labels

If you only want pull requests with a specific label to create preview deployments, you can specify one or multiple in the preview settings.
Dokploy will check that at least one of the labels is present on the pull request. If you leave the settings field empty, Dokploy will create
preview deployments for all pull requests, regardless of labels.

### Monitoring Deployments

When you open a pull request, you can monitor the deployment progress in the preview deployments section:

<ImageZoom src="/assets/images/preview-deploy.png" width={800} height={630} alt='Preview deployments build' className="rounded-lg" />

In this section, you can:
- View the deployment status
- Access the preview URL once deployed
- Check build and deployment logs
- Monitor deployment updates
- Update domain configuration
- Manually rebuild preview deployments

### Automatic Updates

The preview deployment will automatically:
- Update with each new commit to the pull request
- Create a new build and deployment
- Clean up when the pull request is closed or merged

This continuous preview system allows teams to review and test changes in isolation before merging to production.

### Manual Rebuilds

You can manually rebuild a preview deployment without downloading new code from the repository. This is useful when you need to:

- Rebuild with updated environment variables or build settings
- Retry a failed build without making code changes
- Apply configuration changes that require a rebuild

To rebuild a preview deployment, click the **Rebuild** button (hammer icon) next to the deployment and confirm the action. The rebuild will use the existing code and only re-run the build process.

<Callout type="info">
  If you have security or redirects created in your application, it will inherit the same configuration for the preview deployment.
</Callout>

---
title: Rollbacks
description: Learn how to rollback your application in Dokploy.
---

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

Rollbacks are a powerful feature that allows you to easily revert changes to your application. This is particularly useful when you encounter issues or want to revert to a previous version of your application.

## Types of Rollbacks

Dokploy supports two types of rollback mechanisms:

1. **Docker Swarm Rollbacks** (Automatic): Based on health checks, automatically reverts to the previous version if a deployment fails health checks
2. **Registry-based Rollbacks** (Manual): Uses Docker registry to store each deployment's image, allowing you to manually rollback to any specific deployment version

<Callout type="info">
  The rollback methods described in the first section of this guide are based on **Docker Swarm's automatic rollback feature**. Dokploy also supports **registry-based rollbacks** at the deployment level, which allows you to save each deployment's image to a registry and rollback to any specific version. See the "Rollback to a specific version" section below for more details.
</Callout>

## Requirements

1. Have a `/health` endpoint in your application.
2. Have `curl` available in your container (if you use alpine for example, it won't be installed by default).

## Docker Swarm Automatic Rollback

This method uses Docker Swarm's built-in rollback feature, which automatically reverts to the previous version if health checks fail during deployment.

<Callout type="info">
  This rollback method is **automatic** and based on Docker Swarm's health check system. It only works if the new deployment fails health checks, triggering an automatic rollback to the previous version.
</Callout>

### Steps to Configure Automatic Rollback

Let's suppose we have a NodeJS application that has a health check route `/health` that returns a 200 status code and running in the port 3000.

1. In your application is necessary to have a `Path` or `Health Route` to be able to achieve zero downtime deployments eg. in the case of a NodeJS app you can have a route `/health` that returns a 200 status code.
2. Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings`
3. There are a couple options that you can use, in this case we will focus on `Health Check` and `Update Config`.
4. Paste this code in the health check field:
Make sure the API Route exists in your application

```json
{
  "Test": [
    "CMD",
    "curl",
    "-f",
    "http://localhost:3000/health"
  ],
  "Interval": 30000000000,
  "Timeout": 10000000000,
  "StartPeriod": 30000000000,
  "Retries": 3
}
```
5. Now in the `Update Config`

Now when the application is getting unhealthy response from the health check, the container will rollback to the previous version.

Paste the following code:
```json
{
  "Parallelism": 1,
  "Delay": 10000000000,
  "FailureAction": "rollback",
  "Order": "start-first"
}
```

## Registry-based Rollback to Specific Versions

The previous section covered Docker Swarm's automatic rollback feature, which only works when health checks fail. Dokploy also supports **registry-based rollbacks** at the deployment level, which provides more control and flexibility.

### How Registry-based Rollbacks Work

When using registry-based rollbacks, Dokploy:

- **Saves each deployment's image to your configured registry**: Every time you deploy, the built image is tagged and pushed to your Docker registry (Docker Hub, GHCR, etc.)
- **Associates each deployment with its image**: Each deployment record in Dokploy is linked to a specific image tag in your registry
- **Enables rollback to any deployment**: You can rollback to any previous deployment by using the image that was saved during that deployment

This approach is different from Docker Swarm rollbacks because:
- ✅ **Works with any deployment**: Not limited to health check failures
- ✅ **Rollback to any version**: Can rollback to any previous deployment, not just the immediate previous one
- ✅ **Uses registry storage**: Images are stored in your registry, making them persistent and accessible

<Callout type="info">
  Registry-based rollbacks require that your application is configured to use a Docker registry. The images are automatically pushed to your registry during each deployment, and Dokploy tracks which image corresponds to each deployment.
</Callout>

### Prerequisites for Registry-based Rollbacks

To use registry-based rollbacks, you need:

1. **A configured Docker registry** in Dokploy (Docker Hub, GHCR, or custom registry)
2. **Registry credentials** set up in Dokploy's registry settings
3. **Application configured to push images** to the registry during deployment

<Callout type="info">
  When you enable rollbacks, Dokploy will automatically push each deployment's image to your configured registry with a unique tag, allowing you to rollback to any specific deployment version.
</Callout>

### Enabling Registry-based Rollbacks

To start saving deployment images to your registry for rollbacks:

1. Navigate to your application
2. Go to **Deployments** → **Rollback Settings**
3. Enable the **Rollback** option
4. Select the registry you want to use for rollbacks
5. Click on **Save**

Once enabled, Dokploy will:
- **Automatically tag and push images**: Every deployment's image is tagged and pushed to your configured registry
- **Track deployment associations**: Each deployment is linked to its specific image tag in the registry
- **Enable rollback buttons**: You'll see a **Rollback** button next to each deployment in the Deployments section

### Performing a Registry-based Rollback

1. Go to your application's **Deployments** section
2. Find the deployment version you want to rollback to
3. Click the **Rollback** button next to that deployment
4. Confirm the rollback action

<Callout type="info">
  After clicking **Rollback**, you'll need to wait a few seconds for Dokploy to download the image from your registry. The container will not appear in the **Logs** tab immediately - wait a moment for the image download to complete before checking the logs to see the container running.
</Callout>

---
title: Zero Downtime
description: Learn how to configure zero downtime deployments in Dokploy.
---


Dokploy allows you to configure zero downtime deployments, which means that you can deploy your application without any downtime.

By default when you create a new deployment it will stop the latest running container and start the new one. This is the default behavior of Docker Swarm and this leads to Bad Gateway since
the containers are initializing at the same time,
but Dokploy allows you to configure zero downtime deployments.

## Steps to configure Zero Downtime Deployments

Let's suppose we have a NodeJS application that has a health check route `/health` that returns a 200 status code and running in the port 3000.

1. In your application is necessary to have a `Path` or `Health Route` to be able to achieve zero downtime deployments eg. in the case of a NodeJS app you can have a route `/health` that returns a 200 status code.
2. Go to `Advanced` Tab and go to Cluster Settings and enter to `Swarm Settings`
3. There are a couple options that you can use, in this case we will focus on `Health Check`.
4. Paste this code in the health check field:
Make sure the API Route exists in your application

```json
{
  "Test": [
    "CMD",
    "curl",
    "-f",
    "http://localhost:3000/health"
  ],
  "Interval": 30000000000,
  "Timeout": 10000000000,
  "StartPeriod": 30000000000,
  "Retries": 3
}
```

## Example

1. We will use this example [Github Repo](https://github.com/Dokploy/swarm-test)
2. It Have a endpoint called `health` [endpoint](https://github.com/Dokploy/swarm-test/blob/main/index.js#L20) which is the one that will tell us if our application is healthy.
3. For testing purpose I've added a sleep to simulate the delay between the deployments and you can see the bad gateway error.


1. **Use Git Provider in Your Application**:
   - Repository: `https://github.com/Dokploy/swarm-test`
   - Branch: `main`
   - Build path: `/`

If you want to test that there is no zero downtime yet, you can simply deploy the application and then create another deployment and while doing the deployment reload the page in the path /health and you will see that a bad gateway will appear.

Now go to the advanced section of our application, and go to the Swarm Settings section, we are going to modify the first section of Healtchecks.

We will use this configuration specifically, paste and save it

```json
{
  "Test": [
    "CMD",
    "curl",
    "-f",
    "http://localhost:3000/health"
  ],
  "Interval": 30000000000,
  "Timeout": 10000000000,
  "StartPeriod": 30000000000,
  "Retries": 3
}
```

This configuration basically tells to Docker to do:

Make a request inside the container to http://localhost:3000/health and then we are also saying to make in interval of 30000000000 nanosec, and also makes 3 retries before switching to the new container

that would be all, Now you have Zero Downtime Deployments 🎊.

---
title: Dokploy Cloud
description: "Deploy your apps to multiple servers remotely without worrying about the underlying infrastructure."
---

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.

<Callout type="info">
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).
</Callout>

## 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).

---
title: Backups
description: "Learn how to schedule and manage backups for your databases in Dokploy, with options for storage in S3 buckets."
---

Dokploy provides an integrated solution for backing up your databases, ensuring data safety and recovery capabilities.

## Backing Up Your Database

To configure database backups, navigate to the `Backup` tab within your Dokploy dashboard. Here’s what you’ll need to set up:

- **Select Destination S3 Bucket**: Specify where your backups will be stored. Buckets can be configured in the `/dashboard/settings/destinations` route.
- **Database Name**: Enter the name of the database you want to backup.
- **Schedule Cron**: Define the schedule for your backups using cron syntax.
- **Prefix**: Choose a prefix under which backups will be stored in your bucket.
- **Enabled**: Toggle whether backups are active. The default setting is enabled.

### Testing Your Backup Configuration

To ensure your backup settings are correctly configured:

1. Click the `Test` button.
2. This will initiate a test backup to the S3 bucket you selected.
3. Check the bucket to see the result of the test backup.

This feature provides peace of mind by verifying that your backup process is set up correctly before relying on it for operational backups.

---
title: Connection
description: "Learn how to connect to your database using Dokploy."
---

This section explains how to configure database access for applications in Dokploy, including both internal connections within your network and external connections accessible over the internet.

### Internal Credentials

 Used for connecting to the database from within the same network, without exposing the database to the internet.

- **User**: Username for the database access.
- **Password**: Secure password for database access.
- **Database Name**: The name of the database to connect to.
- **Internal Host**: The hostname or internal identifier for the database within the network.
- **Internal Port (Container)**: The port used within the container to connect to the database.
- **Internal Connection URL**: The full connection string used internally to connect to the database.

### External Credentials

Enables the database to be reachable from the internet, necessary for remote management or external applications.

- **External Port (Internet)**: Assign a port that is not currently used by another service to expose the database externally.
  
#### Steps to Configure External Access
1. Ensure the external port is available and not in conflict with other services.
2. Enter the external port you wish to use to expose your database.
3. The system will automatically generate an external connection URL, which can be used to access the database from any database management tool over the internet, like phpMyAdmin, MySQL Workbench, PgAdmin, etc.

### Important Note

For security reasons, internal credentials should be used for applications running within the same network or environment to prevent unauthorized access. External credentials should only be used when necessary and with proper security measures in place, such as VPNs or IP whitelisting.

---
title: MariaDB
description: This guide will cover how to connect from Beekeeper Studio to your mariadb databases in dokploy.
---

1. Download and install Beekeeper Studio [Beekeeper Studio](https://www.beekeeperstudio.io/get).
2. Go to your `mariadb` databases.
3. In External Credentials, enter the `External Port (Internet)` make sure the port is not in use by another service eg. `3307` and click `Save`.
4. It will display the `External Connection URL` eg. `mysql://user:password@1.2.4.5:3306/database`.

Open Beekeeper Studio and follow the steps:

1. Click on `Add New Server`.
2. Select `MariaDB` as the `Database Type`.
3. Use `Import URL` to enter the `External Connection URL` from Dokploy eg. `mysql://user:password@1.2.4.5:3306/database`.
4. Click on `Connect`.
5. Click on `Save`.

Done! now you can manage the database from Beekeeper Studio.

---
title: Mongo Compass
description: This guide will cover how to configure a Mongo Compass connection for your applications in dokploy or panel.
---

1. Download and install Mongo Compass [Mongo Compass](https://www.mongodb.com/try/download/compass).
2. Go to your `MongoDB` databases.
3. In External Credentials, enter the `External Port (Internet)` make sure the port is not in use by another service eg. `27017` and click `Save`.
4. It will display the `External Connection URL` eg. `mongodb://user:password@1.2.4.5:27017/database`.

Open Mongo Compass and follow the steps:

1. Click on `Add Connection`.
2. Copy and paste the `External Connection URL` eg. `mongodb://user:password@1.2.4.5:27017/database`.
3. Click on `Connect`.


Done! now you can manage the database from Mongo Compass.

---
title: MySQL 
description: This guide will cover how to connect from Beekeeper Studio to your mysql databases in dokploy.
---

1. Download and install Beekeeper Studio [Beekeeper Studio](https://www.beekeeperstudio.io/get).
2. Go to your `mysql` databases.
3. In External Credentials, enter the `External Port (Internet)` make sure the port is not in use by another service eg. `3306` and click `Save`.
4. It will display the `External Connection URL` eg. `mysql://user:password@1.2.4.5:3306/database`.

Open Beekeeper Studio and follow the steps:

1. Click on `Add New Server`.
2. Select `MySQL` as the `Database Type`.
3. Use `Import URL` to enter the `External Connection URL` from Dokploy eg. `mysql://user:password@1.2.4.5:3306/database`.
4. Click on `Connect`.
5. Click on `Save`.

Done! now you can manage the database from Beekeeper Studio.

---
title: PG Admin
description: This guide will cover how to connect from pgAdmin to your postgres databases in dokploy.
---

1. Download and install pgAdmin [pgAdmin](https://www.pgadmin.org/download/).
2. Go to your `postgres` databases.
3. In External Credentials, enter the `External Port (Internet)` make sure the port is not in use by another service eg. `5433` and click `Save`.
4. It will display the `External Connection URL` eg. `postgres://user:password@1.2.4.5:5433/database`.


Open pgAdmin and follow the steps:

1. Click on `Add New Server`.
2. Enter the `Server Name` eg. `dokploy`.
3. Enter to `Connection`.
4. In Hostname/Address enter the IP from the server where the database is hosted eg. `1.2.4.5`.
5. In Port enter the port where the database is running eg. `5433`.
6. In Database enter the name of the database eg. `database`.
7. In Username enter the username eg. `user`.
8. In Password enter the password eg. `password`.
9. Click on `Save`.

Done! now you can manage the database from pgAdmin.

---
title: Redis
description: This guide will cover how to connect from RedisInsight to your redis databases in dokploy.
---

1. Download and install RedisInsight [RedisInsight](https://redis.io/insight/).
2. Go to your `redis` databases.
3. In External Credentials, enter the `External Port (Internet)` make sure the port is not in use by another service eg. `6379` and click `Save`.
4. It will display the `External Connection URL` eg. `redis://user:password@1.2.4.5:6379/database`.

Open RedisInsight and follow the steps:


1. Add Redis Database.
2. Enter the `Host` eg. `1.2.4.5`.
3. Enter the `Port` eg. `6379`.
4. Enter the username eg. `default`.
5. Enter the `Password` eg. `password`.
6. Click on `Save`.

Done! now you can manage the database from RedisInsight.

---
title: Databases
description: "Discover how to create and backup databases easily with Dokploy, supporting a variety of database systems."
---

Dokploy simplifies the process of creating and managing databases, offering robust options for both setup and backups.

## Database Support

Dokploy currently supports a range of popular database systems, ensuring compatibility and flexibility for your projects:

- **Postgres**: Robust, SQL-compliant and highly reliable.
- **MySQL**: Widely used relational database known for its performance and flexibility.
- **MariaDB**: A fork of MySQL with additional features and improved performance.
- **MongoDB**: A NoSQL database known for its high scalability and flexibility.
- **Redis**: An in-memory key-value store often used as a database, cache, and message broker.


We offer multiple functionalities that you can use to manage your databases, such as:

## General

Actions like deploying, updating, and deleting your database, and stopping it.

## Environment

If you need to assign environment variables to your application, you can do so here.

In case you need to use a multiline variable, you can wrap it in double quotes just like this `'"here_is_my_private_key"'`.

## Monitoring

Four graphs will be displayed for the use of memory, CPU, disk, and network. Note that the information is only updated if you are viewing the current page, otherwise it will not be updated.

## Backups

We offer automated backups for your databases, ensuring that you can recover your data quickly and easily in case of any issues, you can setup a S3 Destinations in settings to store your backups.


## Logs

If you want to see any important logs from your application that is running, you can do so here and determine if your application is displaying any errors or not.

## Advanced

This section provides advanced configuration options for experienced users. It includes tools for custom commands within the container, managing Docker Swarm settings, and adjusting cluster settings such as replicas and registry selection. These tools are typically not required for standard application deployment and are intended for complex management and troubleshooting tasks.

- **Custom Docker Image**: You can change the Docker image used to run your database.
- **Run Command**: Execute custom commands directly in the container for advanced management or troubleshooting.
- **Volumes**: To ensure data persistence across deployments, configure storage volumes for your application.
- **Resources**: Adjust the CPU and memory allocation for your application.
- **Danger Zone**: If for some reason you want to start again and delete all the data, tables, etc. you can do it here.

## Keyboard Shortcuts

To help speed up navigating there are some built in keyboard shortcuts for
navigating tabs on database pages. Similar to GitHub these are all prefixed
with the `g` key so to use them press `g` and then the shortcut key.

| Key | Tab                 |
| --- | ------------------- |
| `g` | General             |
| `e` | Environment         |
| `l` | Logs                |
| `m` | Monitoring          |
| `b` | Backups             |
| `a` | Advanced            |

---
title: Restore
description: "Learn how to restore your databases in Dokploy, with options for restoring from S3 buckets."
---



## Restoring from S3 Buckets

To restore your database from an S3 bucket, navigate to the `Backup` tab and click on the `Restore` button within your Dokploy dashboard. Here’s what you’ll need to set up:

- **Select Source S3 Bucket**: Specify the S3 bucket where your backup files are stored.
- **Search for Backup File**: Enter the name of the backup file you want to restore(it will autocomplete based on the files in the bucket)
- **Database Name**: Enter the name of the database you want to restore to.
- **Restore Database**: Click the `Restore` button to start the restoration process.

If you previously used the backups generated by dokploy, it will automatically use the correct commands to restore your database.

Other formats are not guaranteed to work.

<Callout type="info">
    If you have nested folders in your S3 Bucket, you can start typing the folder name and it will autocomplete.

    eg. If you have a folder called `backups` and you have a backup file called `backup.sql.gz`, you can start typing `backups/` and it will autocomplete to `backups/backup.sql.gz`.
</Callout>





## Default Backup Commands

This are the default commands that Dokploy uses to generate the backups.

### Postgres

```bash
pg_dump -Fc --no-acl --no-owner -h localhost -U ${databaseUser} --no-password '${database}' | gzip"
```

### MySQL

```bash
mysqldump --default-character-set=utf8mb4 -u 'root' --password='${databaseRootPassword}' --single-transaction --no-tablespaces --quick '${database}' | gzip"
```

### MariaDB

```bash
mariadb-dump --user='${databaseUser}' --password='${databasePassword}' --databases ${database} | gzip"
```

### MongoDB

```bash
mongodump -d '${database}' -u '${databaseUser}' -p '${databasePassword}' --archive --authenticationDatabase=admin --gzip"
```

---
title: Domains
description: Configure domains for your Docker Compose application.
---

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

When using Docker Compose, there are **two ways** to configure domains for your services:

## Method 1: Using Dokploy Domains (Recommended)

The easiest way to configure domains is using Dokploy's native domain management feature. This method allows you to configure domains directly through the Dokploy UI without manually editing your Docker Compose file.

<Callout type="info">
  **Recommended**: Since v0.7.0, Dokploy supports domains natively. You can configure your domains directly in the Dokploy UI through the **Domains** tab of your Docker Compose application. This is the simplest and most user-friendly approach.
</Callout>

To use this method:
1. Navigate to your Docker Compose application in Dokploy
2. Go to the **Domains** tab
3. Click **Add Domain** and configure your domain
4. Dokploy will automatically handle the routing configuration

### How It Works

At runtime, during the deployment phase, Dokploy automatically adds Traefik labels internally to your Docker Compose file. You don't need to manually add these labels - Dokploy handles this automatically based on the domains you configure in the UI.

**Example:**

Here's a default Docker Compose file:

```yaml
version: "3.8"

services:
  beszel:
    image: henrygd/beszel:0.10.2
    restart: unless-stopped
    ports:
      - 8090
    volumes:
      - beszel_data:/beszel_data
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  beszel_data: {}
```

**Preview Compose Feature:**

You can click the **Preview Compose** button to see the final Docker Compose file that will be executed. If you have at least one domain added, the preview will show the compose file with all the labels and network configurations automatically added.

Here's what the final compose file looks like when deployed (this example uses [Isolated Deployments](/docs/core/docker-compose/utilities#isolated-deployments)):

```yaml
version: "3.8"

services:
  beszel:
    image: henrygd/beszel:0.10.2
    restart: unless-stopped
    ports:
      - 8090
    volumes:
      - beszel_data:/beszel_data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - a-beszel-a95pzl
    labels:
      - traefik.http.routers.a-beszel-a95pzl-715-web.rule=Host(`a-beszel-d073ee-31-220-108-27.traefik.me`)
      - traefik.http.routers.a-beszel-a95pzl-715-web.entrypoints=web
      - traefik.http.services.a-beszel-a95pzl-715-web.loadbalancer.server.port=8090
      - traefik.http.routers.a-beszel-a95pzl-715-web.service=a-beszel-a95pzl-715-web
      - traefik.enable=true

volumes:
  beszel_data: {}

networks:
  a-beszel-a95pzl:
    name: a-beszel-a95pzl
    external: true
```

**Important Notes:**

- If you don't add any domains through the UI and don't use [Isolated Deployments](/docs/core/docker-compose/utilities#isolated-deployments), your application will be deployed exactly as you specified in your original Docker Compose file - no labels or network modifications will be added.
- If you're not using [Isolated Deployments](/docs/core/docker-compose/utilities#isolated-deployments), Dokploy will add the `dokploy-network` to the service you selected, however you need to add `dokploy-network` to the other services to maintain connectivity.
- The Preview Compose button is useful for verifying how Dokploy will modify your compose file before deployment.
- All label generation and network configuration is handled automatically by Dokploy based on your domain settings.

For detailed instructions on using Dokploy's domain management, see the [Domains guide](/docs/core/domains).

## Method 2: Manual Configuration (Advanced)

If you prefer to configure domains manually using Traefik labels in your Docker Compose file, you can do so by following the steps below. This method gives you more control but requires manual configuration.

<Callout type="warn">
  Manual configuration is more complex and requires editing your Docker Compose file. We recommend using Method 1 (Dokploy Domains) unless you have specific requirements that need manual Traefik label configuration.
</Callout>

### Manual Configuration Steps

Key Steps for manual configuration:

1. Add the service to the `dokploy-network`.
2. Use Traefik labels to configure routing.

### Example Scenario

Let's consider an application with three components: a frontend, a backend, and a database. We'll start with a basic Docker Compose file and then enhance it with manual domain configuration.

```yaml
version: "3.8"

services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    volumes:
      - ./frontend:/app
    ports:
      - "3000:3000"
    depends_on:
      - backend

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    volumes:
      - ./backend:/app
    ports:
      - "5000:5000"
    environment:
      - DATABASE_URL=postgres://postgres:password@database:5432/mydatabase
    depends_on:
      - database

  database:
    image: postgres:13
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydatabase
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:
```

### Step 1: Add the Network

First, we'll add the dokploy-network to our services:

<Callout type="info">
  **Tip**: If you prefer to isolate all services and avoid adding them to the `dokploy-network`, you can use the **Isolated Deployments** feature. This feature isolates all services and eliminates the need to manually add them to the dokploy-network. See the [Isolated Deployments guide](/docs/core/docker-compose/utilities#isolated-deployments) for more information.
</Callout>

```yaml
version: "3.8"

services:
  frontend:
    # ... (previous configuration)
    networks:
      - dokploy-network

  backend:
    # ... (previous configuration)
    networks:
      - dokploy-network

  database:
    # ... (previous configuration)
    networks:
      - dokploy-network

volumes:
  db-data:

networks:
  dokploy-network:
    external: true
```

### Step 2: Configuring Traefik Labels

Now, let's add Traefik labels to route domains to our services. We'll focus on the frontend and backend services:

<Callout type="warn">
  **Important for Docker Stack**: If you're using **Docker Stack** (Docker Swarm mode), the Traefik labels must be placed in the `deploy.labels` section instead of directly in the `labels` section. See the Docker Stack example below.
</Callout>

```yaml
version: "3.8"

services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    volumes:
      - ./frontend:/app
    expose:
      - 3000
    depends_on:
      - backend
    networks:
      - dokploy-network
    labels:
      - traefik.enable=true
      - traefik.http.routers.frontend-app.rule=Host(`frontend.dokploy.com`)
      - traefik.http.routers.frontend-app.entrypoints=web
      - traefik.http.services.frontend-app.loadbalancer.server.port=3000

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    volumes:
      - ./backend:/app
    expose:
      - 5000
    environment:
      - DATABASE_URL=postgres://postgres:password@database:5432/mydatabase
    depends_on:
      - database
    networks:
      - dokploy-network
    labels:
      - traefik.enable=true
      - traefik.http.routers.backend-app.rule=Host(`backend.dokploy.com`)
      - traefik.http.routers.backend-app.entrypoints=web
      - traefik.http.services.backend-app.loadbalancer.server.port=5000

  database:
    # ... (same as before)

volumes:
  db-data:

networks:
  dokploy-network:
    external: true
```

### Understanding Traefik Labels

1. `traefik.enable=true` Enables Traefik routing for the service.
2. `traefik.http.routers.<UNIQUE-RULE>.rule=Host('your-domain.dokploy.com')` Specifies the domain for the service
3. `traefik.http.routers.<UNIQUE-RULE>.entrypoints=web` Sets the service to be accessible via HTTP.
4. `traefik.http.services.<UNIQUE-RULE>.loadbalancer.server.port=3000` Specifies the port your service is using internally.

**Note**: Replace `<UNIQUE-RULE>` with a unique identifier for each service (e.g., frontend-app, backend-app, etc.).

#### Docker Stack Configuration

When using **Docker Stack** (Docker Swarm mode), labels must be placed under the `deploy.labels` section. Additionally, Docker Stack does not support the `build` directive, so you must use pre-built images from a registry:

<Callout type="warn">
  **Important**: Docker Stack does not support the `build` directive. You must build your images separately and push them to a Docker registry, then reference them using the `image:` directive.
</Callout>

```yaml
version: "3.8"

services:
  frontend:
    image: your-registry.com/frontend:latest  # Pre-built image from registry
    volumes:
      - ./frontend:/app
    expose:
      - 3000
    networks:
      - dokploy-network
    deploy:
      labels:
        - traefik.enable=true
        - traefik.http.routers.frontend-app.rule=Host(`frontend.dokploy.com`)
        - traefik.http.routers.frontend-app.entrypoints=web
        - traefik.http.services.frontend-app.loadbalancer.server.port=3000

  backend:
    image: your-registry.com/backend:latest  # Pre-built image from registry
    volumes:
      - ./backend:/app
    expose:
      - 5000
    networks:
      - dokploy-network
    deploy:
      labels:
        - traefik.enable=true
        - traefik.http.routers.backend-app.rule=Host(`backend.dokploy.com`)
        - traefik.http.routers.backend-app.entrypoints=web
        - traefik.http.services.backend-app.loadbalancer.server.port=5000

networks:
  dokploy-network:
    external: true
```

<Callout type="info">
  The key differences for **Docker Stack** are:
  1. Labels must be nested under `deploy.labels` (not directly under `labels`)
  2. You must use `image:` with a pre-built image from a registry (Docker Stack does not support `build`)
  3. Build your images separately and push them to a registry before deploying with Docker Stack
</Callout>

### Important Considerations

1. **Port Exposure**: Use `expose` instead of `ports` to limit port access to the container network, avoiding exposure to the host machine.
2. **DNS Configuration**: Ensure you create `A` records pointing to your domain in your DNS Provider Settings.
3. **HTTPS**: For HTTPS, you can use Let's Encrypt or other SSL/TLS certificates.
4. **Isolated Deployments**: As an alternative to manually adding services to `dokploy-network`, you can use the [Isolated Deployments](/docs/core/docker-compose/utilities#isolated-deployments) feature, which automatically isolates all services and handles networking configuration for you.

### Deployment

With these manual configurations in place, you're now ready to deploy your application using Docker Compose. This setup should be sufficient to get your services up and running with custom domain routing through Traefik.

<Callout type="info">
  Remember: For most use cases, we recommend using **Method 1 (Dokploy Domains)** as it's simpler and doesn't require manual Docker Compose file editing. See the [Domains guide](/docs/core/domains) for more information.
</Callout>

If you have any further questions or need assistance, join our [Discord server](https://discord.com/invite/2tBnJ3jDJc) and we'll be happy to help.

---
title: "Example"
description: "Learn how to use Docker Compose with Dokploy"

---

## Tutorial

In this tutorial, we will create a simple application using Docker Compose and route the traffic to an accessible domain.

<Callout type="info">
  **Note**: There are two ways to configure domains for Docker Compose applications:
  1. **Using Dokploy Domains** (Recommended): Configure domains directly in the Dokploy UI through the **Domains** tab. See the [Domains guide](/docs/core/domains) for details.
  2. **Manual Configuration**: Configure domains using Traefik labels in your Docker Compose file (shown in this tutorial).

  This tutorial demonstrates the manual method. For most users, we recommend using the Dokploy Domains feature as it's simpler and doesn't require editing your Docker Compose file.
</Callout>


### Steps

1. Create a new project.
2. Create a new service `Compose` and select the Compose Type `Docker Compose`.
3. Fork this repository: [Repo](https://github.com/Dokploy/docker-compose-test).
4. Select Provider type: GitHub or Git.
5. Select the repository: `Dokploy/docker-compose-test`.
6. Select the branch: `main`.
7. Set the Compose Path to `./docker-compose.yml` and save.
![Docker compose configuration](/assets/images/compose/setup.png)


### Updating Your `docker-compose.yml`

Add the following to your existing `docker-compose.yml` file:

1. Add the network `dokploy-network` to each service.
2. Add labels for Traefik to make the service accessible through the domain.

Example:

Let's modify the following compose file to make it work with Dokploy:

```yaml
version: "3"

services:
  next-app:
    build:
      context: ./next-app
      dockerfile: prod.Dockerfile
      args:
        ENV_VARIABLE: ${ENV_VARIABLE}
        NEXT_PUBLIC_ENV_VARIABLE: ${NEXT_PUBLIC_ENV_VARIABLE}
    restart: always
    ports:
      - 3000:3000
    networks:
      - my_network
networks:
  my_network:
    external: true
```


Updated version with dokploy-network and Traefik labels:

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

<Callout  type="warn">
Don't set container_name property to the each service, it will cause issues with logs, metrics and other features
</Callout>
{/* :::danger
Don't set container_name property to the each service, it will cause issues with logs, metrics and other features

::: */}

```yaml
version: "3"

services:
  next-app:
    build:
      context: ./next-app
      dockerfile: prod.Dockerfile
      args:
        ENV_VARIABLE: ${ENV_VARIABLE}
        NEXT_PUBLIC_ENV_VARIABLE: ${NEXT_PUBLIC_ENV_VARIABLE}
    restart: always
    ports:
      - 3000
    networks:
      - dokploy-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.<unique-name>.rule=Host(`your-domain.com`)"
      - "traefik.http.routers.<unique-name>.entrypoints=websecure"
      - "traefik.http.routers.<unique-name>.tls.certResolver=letsencrypt"
      - "traefik.http.services.<unique-name>.loadbalancer.server.port=3000"
networks:
  dokploy-network:
    external: true
```

Make sure to point the A record to the domain you want to use for your service.

<ImageZoom  src="/assets/images/compose/domain.png" width={800} height={630} alt='home og image' className="rounded-lg" />

Deploy the application by clicking on "deploy" and wait for the deployment to complete. Then give Traefik about 10 seconds to generate the certificates. You can then access the application through the domain you have set.

<ImageZoom  src="/assets/images/compose/application.png" width={800} height={630} alt='home og image' className="rounded-lg" />

**Tips**:

1. Set unique names for each router: `traefik.http.routers.<unique-name>` 
2. Set unique names for each service: `traefik.http.services.<unique-name>`
3. Ensure the network is linked to the `dokploy-network`
4. Set the entry point to websecure and the certificate resolver to letsencrypt to generate certificates.
5. **For Docker Stack**: If you're using Docker Stack (Docker Swarm mode), place the labels under `deploy.labels` instead of directly under `labels`. See the [Domains guide](/docs/core/docker-compose/domains) for the Docker Stack configuration example.

---
title: Docker Compose
description: "Learn how to use Docker Compose with Dokploy"
---

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

Dokploy integrates with Docker Compose and Docker Stack to provide flexible deployment solutions. Whether you are developing locally or deploying at scale, Dokploy facilitates application management through these powerful Docker tools.

### Configuration Methods

Dokploy provides two methods for creating Docker Compose configurations:

- **Docker Compose**: Ideal for standard Docker Compose configurations.
- **Stack**: Geared towards orchestrating applications using Docker Swarm. Note that some Docker Compose features, such as `build`, are not available in this mode.

### General

Configure the source of your code, the way your application is built, and also manage actions like deploying, updating, and deleting your application, and stopping it.

### Environment

The code editor in Dokploy allows you to define environment variables for your Docker Compose deployment. By default, Dokploy saves these variables to a `.env` file in the same directory as your `docker-compose.yml`.

<Callout type="warning">
Environment variables set in the UI are written to the `.env` file, but are **not automatically injected into containers**. You have two options:

**1. Inject all variables** — Use the `env_file` option in your `docker-compose.yml` to load every variable from the `.env` file into the container:

```yaml
services:
  app:
    env_file:
      - .env
```

**2. Use specific variables** — Reference only the variables you need using the standard `${VAR_NAME}` syntax in your `docker-compose.yml`:

```yaml
services:
  app:
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - API_KEY=${API_KEY}
```
</Callout>

### Monitoring

Monitor each service individually within Dokploy. If your application consists of multiple services, each can be monitored separately to ensure optimal performance.

### Logs

Access detailed logs for each service through the Dokploy log viewer, which can help in troubleshooting and ensuring the stability of your services.

### Deployments

You can view the last 10 deployments of your application. When you deploy your application in real time, a new deployment record will be created and it will gradually show you how your application is being built.

We also offer a button to cancel deployments that are in queue. Note that those in progress cannot be canceled.

We provide a webhook so that you can trigger your own deployments by pushing to your GitHub, Gitea, GitLab, Bitbucket repository.

### Advanced

This section provides advanced configuration options for experienced users. It includes tools for custom commands within the container and volumes.

- **Command**: Dokploy has a defined command to run the Docker Compose file, ensuring complete control through the UI. However, you can append flags or options to the command.
  
  <Callout type="info" title="Using Private Registries with Docker Stack">
  If you're deploying with **Docker Stack** (Docker Swarm mode) using **replicas** and a **private registry**, you need to add the `--with-registry-auth` flag to ensure that registry credentials are properly distributed to all nodes in your swarm.
  
  Without this flag, worker nodes may fail to pull images from private registries, resulting in authentication errors like "no such image" or "docker authentication failed".
  
  This flag ensures that Docker shares the registry credentials with all swarm nodes during deployment, enabling them to authenticate and pull images from your private registry (GitHub Container Registry, Docker Hub private repos, etc.).
  </Callout>

- **Volumes**: To ensure data persistence across deployments, configure storage volumes for your application.

<ImageZoom
  src="/assets/images/compose/overview.png"
  width={800}
  height={630}
  quality={100}
  priority
  alt="home og image"
  className="rounded-lg"
/>

<Callout title="Volumes">
Docker volumes are a way to persist data generated and used by Docker containers. They are particularly useful for maintaining data between container restarts or for sharing data among different containers.

Dokploy supports two methods for data persistence in Docker Compose:

### Method 1: Bind Mounts (../files folder)

Use bind mounts for simple persistence needs, configuration files, or when you need direct access to files on the host. This method maps a directory from the host machine into the container.

**Important:** Avoid using absolute host paths, as they will be cleaned up during deployments:

```yaml
volumes:
  - "/folder:/path/in/container" ❌
```

Instead, use the `../files` folder to ensure your data persists between deployments:

```yaml
volumes:
  - "../files/my-database:/var/lib/mysql" ✅
  - "../files/my-configs:/etc/my-app/config" ✅
```

**Use bind mounts when:**
- You need simple data persistence
- You're mounting configuration files or small datasets
- You want direct file access on the host
- You don't need automated backups via Dokploy's Volume Backups feature

### Method 2: Docker Named Volumes

Use Docker named volumes when you need automated backups, better portability, or Docker-managed storage. Named volumes are managed by Docker and can be backed up automatically using Dokploy's [Volume Backups](/docs/core/volume-backups) feature.

```yaml
services:
  app:
    image: dokploy/dokploy:latest
    volumes:
      - my-database:/var/lib/mysql
      - my-app-data:/app/data

volumes:
  my-database:
  my-app-data:
```

**Use named volumes when:**
- You need automated backups to S3 (via Volume Backups)
- You want Docker-managed storage (better portability)
- You're storing databases or large datasets
- You need backup and restore capabilities

**Note:** Volume Backups only work with Docker named volumes, not with bind mounts (`../files`). If you need backup functionality, use named volumes instead of bind mounts.

### Choosing the Right Method

| Feature | Bind Mounts (../files) | Named Volumes |
|---------|----------------------|---------------|
| Simple persistence | ✅ Yes | ✅ Yes |
| Direct host access | ✅ Yes | ❌ No |
| Automated backups | ❌ No | ✅ Yes |
| Docker-managed | ❌ No | ✅ Yes |
| Best for config files | ✅ Yes | ⚠️ Possible but less common |
| Best for databases | ⚠️ Possible | ✅ Recommended |

**Important:** If you need to use files from your repository (configuration files, scripts, etc.), you must move them to Dokploy's File Mounts (via Advanced → Mounts) instead of mounting them directly from the repository. When using AutoDeploy, Dokploy performs a `git clone` on each deployment, which clears the repository directory. Mounting files directly from your repository using relative paths (e.g., `./` or `./config/file.conf`) will cause them to be lost or empty in subsequent deployments. See the [Troubleshooting guide](/docs/core/troubleshooting#using-files-from-your-repository) for more details.

</Callout>

## Keyboard Shortcuts

To help speed up navigating there are some built in keyboard shortcuts for
navigating tabs on docker compose pages. Similar to GitHub these are all prefixed
with the `g` key so to use them press `g` and then the shortcut key.

| Key | Tab                 |
| --- | ------------------- |
| `g` | General             |
| `e` | Environment         |
| `u` | Domains             |
| `d` | Deployments         |
| `b` | Backups             |
| `s` | Schedules           |
| `v` | Volume Backups      |
| `l` | Logs                |
| `m` | Monitoring          |
| `a` | Advanced            |

---
title: Utilities
description: "Utilities for your Docker Compose application"
---

Dokploy provides a set of utilities to enhance your Docker Compose application deployment experience.

## Isolated Deployments

All open source templates come with this feature enabled by default.

This feature allows you to deploy your application in a separate network, isolated from other applications. This isolation is particularly useful when you need to deploy multiple instances of the same application.

For example, if you want to deploy two WordPress instances, you would typically encounter service naming conflicts since they share the same network (dokploy-network). Docker doesn't allow services with identical names in the same network. Consider this typical WordPress service:

```yaml
services:
  wordpress:
    image: wordpress:latest
    ports:
      - "80"
```

<ImageZoom
  src="/assets/images/compose-isolate.png"
  alt="Isolated Deployments"
  width={1000}
  height={600}
/>

When Isolated Deployments is enabled, Dokploy will:

1. Create a network based on your `appName` and associate it with each service in your compose file
2. Add the network to every service in your compose file
3. Connect the Traefik load balancer to this isolated network, maintaining service isolation while ensuring proper routing

When using this feature, you don't need to explicitly define dokploy-network in your networks section, as isolation is handled automatically.

<Callout type="warn">
  **Important: Installation Type Considerations**

  If you're using a **custom installation** that replaces the standalone Traefik container with a Docker service (see [Manual Installation](/docs/core/manual-installation)), be aware of the following risks:

  1. **System Restart Issues**: If your system restarts, your services may lose their network references to Traefik. This happens because Docker Swarm changes network references after a restart, which can cause connectivity issues between your services and Traefik.

  2. **Manual Redeployment Required**: After a system restart, you may need to manually redeploy your Docker Compose applications to restore network connectivity, which can be tedious and time-consuming.

  3. **Reference**: For more details about this issue, see [GitHub Issue #1004](https://github.com/Dokploy/dokploy/issues/1004).

  **Recommended Approach**: If you use the **official installation** or **manual installation with the standalone Traefik container**, you won't experience these issues. Your services should start normally after a system restart without requiring manual intervention.
</Callout>

---
title: Cloudflare
description: This guide will cover how to configure a Cloudflare domain for your applications in dokploy or panel.
---

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

Cloudflare has multiple SSL's Modes:

1. **Strict (SSL-Only Origin Pull)**: Enforce encryption between Cloudflare and your origin. Use this mode to guarantee connections to your origin will always be encrypted, regardless of your visitor’s request.
2. **Full (Strict)**: Enable encryption end-to-end and enforce validation on origin certificates. Use Cloudflare’s Origin CA to generate certificates for your origin.
3. **Full**: Enable encryption end-to-end. Use this mode when your origin server supports SSL certification but does not use a valid, publicly trusted certificate.
4. **Flexible**: Enable encryption only between your visitors and Cloudflare. This will avoid browser security warnings, but all connections between Cloudflare and your origin are made through HTTP.
5. **Off (not secure)**: No encryption applied. Turning off SSL disables HTTPS and causes browsers to show a warning that your website is not secure.

We will cover two of SSL modes in this guide:

- **Full (Strict)**
- **Flexible**

## Switch Mode

To switch between modes, follow these steps:

1. Go to cloudflare dashboard and then click on `Account Home` -> Select the Domain you want to change.
2. On the left side, click `SSL/TLS`.
3. Click on `Overview`.
4. Click on Configure SSL/TLS Encryption.
5. Select the desired mode Full (Strict) or Flexible.
6. Click `Save`.




## Assign a Domain Full (Strict)


<Callout type="warn">
Follow the steps in the same order to prevent any issues.
</Callout>

You can create a certificate for your origin server using two methods:
- Using Let's Encrypt to generate a certificate for your origin server.
- Using Cloudflare's Origin CA to generate a certificate for your origin server.

We assume that you have enabled the `Full (Strict)` mode in the previous step, is super important to follow the steps in the same order to prevent any issues.

### Using Let's Encrypt
1. Go to cloudflare dashboard and then click on `Account Home` -> Select the Domain.
2. On the left side, click `DNS`.
3. Click on `Records`.
4. Click on `Add Record`.
5. Select `A` record type.
6. Enter the `Host` name, eg. `api` so it will be `api.dokploy.com`.
7. Enter the `IPv4 Address` from your server where the application is hosted eg. `1.2.3.4`.
8. Click `Save`.
9. Go to dokploy panel and now you can assign either for `Applications` or `Docker Compose`.
10. Go to `Domains` section.
11. Click `Create Domain`.
12. In the `Host` field, enter the domain name eg. `api.dokploy.com`.
13. In the `Path` field, enter the path eg. `/`.
14. In the `Container Port` field, enter the port where your application is running eg. `3000`.
15. In the `HTTPS` field enable `ON`.
16. In the `Certificate` field select `Let's Encrypt`.
17. Click `Create`.
18. A domain will be automatically assigned to your application.
19. Wait a few seconds and refresh the application.
20. You should see the application running on the domain you just created.

### Using Cloudflare's Origin CA
1. Go to cloudflare dashboard and then click on `Account Home` -> Select the Domain.
2. On the left side, click `SSL/TLS`.
3. Click on `Origin Server`.
4. Click on `Create Certificate`.
5. Select `Generate private key and CSR with Cloudflare`.
6. Choose the list of hostnames you want the certificate to cover eg. `api.dokploy.com`.
7. Choose the validity period eg. `15 years`.
8. Click `Create`.
9. Using the PEM format, copy the `Origin Certificate` and `Private Key` in the respective fields in the dokploy new certificate panel (Certificates > Add Certificate).
10. Go to `Domains` section in your application.
11. Click `Create Domain`.
12. In the `Host` field, enter the domain name eg. `api.dokploy.com`. (Make sure that the domain is already pointing to your server IP in Cloudflare DNS settings and the **hostname matches the one in the certificate**).
13. In the `Path` field, enter the path eg. `/`.
14. In the `Container Port` field, enter the port where your application is running eg. `3000`.
15. In the `HTTPS` field enable `ON`.
16. In the `Certificate` field select `None`.
17. Click `Create`.

Using Cloudflare's Origin CA, you are sure that the certificate will be valid for the next 15 years, or the duration you selected, and you don't have to worry about failed renewals.

<Callout type="info">
You can also create a certificate for wildcards domains eg. `*.dokploy.com` and use it for multiple subdomains.
</Callout>

<Callout type="warn">
**Important**: With a free Cloudflare account, this methods work only for the main domain and subdomains, not for sub-subdomains. Eg. `api.dokploy.com` works but `staging.api.dokploy.com` does not work.
</Callout>



## Assign a Domain Flexible

We assume that you have enabled the `Flexible` mode in the previous step, is super important to follow the steps in the same order to prevent any issues.

1. Go to cloudflare dashboard and then click on `Account Home` -> Select the Domain.
2. On the left side, click `DNS`.
3. Click on `Records`.
4. Click on `Add Record`.
5. Select `A` record type.
6. Enter the `Host` name, eg. `api` so it will be `api.dokploy.com`.
7. Enter the `IPv4 Address` from your server where the application is hosted eg. `1.2.3.4`.
8. Click `Save`.
9. Go to dokploy panel and now you can assign either for `Applications` or `Docker Compose`.
10. Go to `Domains` section.
11. Click `Create Domain`.
12. In the `Host` field, enter the domain name eg. `api.dokploy.com`.
13. In the `Path` field, enter the path eg. `/`.
14. In the `Container Port` field, enter the port where your application is running eg. `3000`.
15. In the `HTTPS` field enable `OFF`.
16. In the `Certificate` field select `None`.
17. Click `Create`.
18. A domain will be automatically assigned to your application.
19. Wait a few seconds and refresh the application.
20. You should see the application running on the domain you just created.


### Important Clarification on Container Ports

The "Container Port" specified in the domain settings is exclusively for routing traffic to the correct application container through Traefik, and does not expose the port directly to the internet. This is fundamentally different from the port settings in the "Advanced -> Ports" section, which are used to directly expose application ports. The container port in the domain settings ensures that Traefik can internally direct traffic to the specified port within the container based on the domain configuration.

---
title: Generated
description: This section outlines how to configure free HTTP domains for your applications in Dokploy, ensuring that your applications are accessible via custom URLs.
---


Dokploy use https://traefik.me to generate free domains for you.
Quickly set up a domain for development or testing purposes without needing to register a domain.


#### Steps to Generate a Domain

1. Go to the `domains` section.
2. Click `Create Domain`.
3. Click on the `Dice` Icon next to `Host` field it will generate a free domain for you.
4. Path is `/`.
5. `Container Port`, set the port where your application is running, eg usually for Next.js it is `3000`, for Astro is `4321`
6. HTTPS is `OFF`.
7. Certificate is `None`.
8. Click `Create`.
9. A free domain will be automatically assigned to your application.


### Important Clarification on Container Ports

The "Container Port" specified in the domain settings is exclusively for routing traffic to the correct application container through Traefik, and does not expose the port directly to the internet. This is fundamentally different from the port settings in the "Advanced -> Ports" section, which are used to directly expose application ports. The container port in the domain settings ensures that Traefik can internally direct traffic to the specified port within the container based on the domain configuration.

---
title: Others
description: This guide will cover how to configure a domain from other providers for your applications in dokploy or panel.
---


In the case you don't want to use Cloudflare, you can use any domain from any provider:


1. Go to your DNS Panel.
2. Go to `Records` section.
3. Click on `Add Record`.
4. Select `A` record type.
5. Enter the `Host` name, eg. `api` so it will be `api.dokploy.com`.
6. Enter the `IPv4 Address` from your server where the application is hosted eg. `1.2.3.4`.
7. Click `Save`.
8. Go to dokploy panel and now you can assign either for `Applications` or `Docker Compose`.
9. Go to `Domains` section.
10. Click `Create Domain`.
11. In the `Host` field, enter the domain name eg. `api.dokploy.com`.
12. In the `Path` field, enter the path eg. `/`.
13. In the `Container Port` field, enter the port where your application is running eg. `3000`.
14. In the `HTTPS` field enable `ON`.
15. In the `Certificate` field select `Let's Encrypt`.
16. Click `Create`.
17. A domain will be automatically assigned to your application.
18. Wait a few seconds and refresh the application.
19. You should see the application running on the domain you just created.


### Important Clarification on Container Ports

The "Container Port" specified in the domain settings is exclusively for routing traffic to the correct application container through Traefik, and does not expose the port directly to the internet. This is fundamentally different from the port settings in the "Advanced -> Ports" section, which are used to directly expose application ports. The container port in the domain settings ensures that Traefik can internally direct traffic to the specified port within the container based on the domain configuration.