Advanced

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

For complete setup instructions, configuration details, and best practices, please read the comprehensive Build Server guide.

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.

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

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)

Docker API Reference

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

{
  "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

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.

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.