Multi-Server Deployment

Dokploy supports multi-server deployments, allowing you to manage infrastructure across multiple remote machines from a centralized control plane.

Server Types

Dokploy supports two distinct server types, each optimized for specific workloads:

Deploy Server

Full-featured servers for running production applications with Traefik, Docker Swarm, and monitoring capabilities.

Build Server

Dedicated servers for building Docker images with Nixpacks, Buildpacks, and Railpack support.

Server Setup

Requirements

Before adding a server to Dokploy, ensure it meets these requirements:

SSH Access: Root or sudo user access via SSH key authentication
Operating System: Supported Linux distributions (Ubuntu, Debian, CentOS, Fedora, Arch, Alpine, Rocky, RHEL, SLES)
Ports: Open ports for SSH (22), HTTP (80), HTTPS (443), Docker Swarm (2377)
Resources: Minimum 1GB RAM, 10GB disk space

Docker installed via Snap is not supported. If Docker is installed with Snap, remove it before running the setup script.

Adding a Server

Create Server Entry

Add the server to Dokploy with connection details:

const server = await createServer({
  name: "Production Server 1",
  ipAddress: "192.168.1.100",
  port: 22,
  username: "root",
  sshKeyId: "ssh-key-id",
  serverType: "deploy" // or "build"
}, organizationId);

Validate Connection

Before setup, validate the server connection:

const validation = await serverValidate(serverId);

This checks for:

Docker installation and version
RClone availability
Nixpacks installation
Buildpacks availability
Railpack installation
Dokploy network existence
Docker Swarm status
Main directory structure

Run Server Setup

Execute the automated setup script:

await serverSetup(serverId, (log) => {
  console.log(log); // Real-time setup logs
});

The setup process installs and configures:

Docker Engine (v28.5.0)
Docker Swarm
Traefik reverse proxy
Dokploy network
Build tools (Nixpacks, Buildpacks, Railpack)
RClone for backups
Monitoring service (in cloud environments)

Server Setup Process

Deploy Server Installation

For deploy servers, the setup script performs these operations:

1. Install System Utilities

Installs essential packages based on OS:

curl, wget, git, git-lfs
jq, openssl, unzip, tar
Distribution-specific package managers configured

2. Validate Ports

Checks if required ports are available:

Port 80 for HTTP traffic
Port 443 for HTTPS traffic

Warns if ports are already in use.

3. Install RClone

Installs RClone for backup operations:

curl https://rclone.org/install.sh | sudo bash

4. Install Docker

Installs Docker Engine v28.5.0 with OS-specific methods:

Ubuntu/Debian: apt-get
CentOS/RHEL: dnf/yum
Arch Linux: pacman
Alpine: apk

Enables and starts Docker service.

5. Initialize Docker Swarm

Sets up Docker Swarm for orchestration:

docker swarm init --advertise-addr $IP_ADDRESS

Automatically detects IPv4 or IPv6 address.

6. Create Dokploy Network

Creates overlay network for services:

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

7. Setup Directory Structure

Creates required directories:

/etc/dokploy - Main configuration directory
/etc/dokploy/traefik - Traefik config
/etc/dokploy/traefik/dynamic - Dynamic config
/etc/dokploy/monitoring - Monitoring database

8. Configure Traefik

Sets up Traefik reverse proxy:

Creates main configuration file
Configures HTTP/HTTPS entry points
Sets up Let’s Encrypt SSL
Deploys Traefik container

9. Install Build Tools

Installs application build systems:

Nixpacks (v1.41.0) - Nix-based builds
Buildpacks (v0.39.1) - Cloud Native Buildpacks
Railpack (v0.15.4) - Ruby on Rails builds

Build Server Installation

Build servers receive a minimal installation:

Docker Engine
Directory structure
Build tools (Nixpacks, Buildpacks, Railpack)

Build servers do not include Traefik, Docker Swarm, or networking components since they only build images.

Server Management

Update Server Configuration

Modify server settings after creation:

await updateServerById(serverId, {
  name: "Updated Server Name",
  ipAddress: "new-ip-address",
  port: 2222,
  metricsConfig: {
    server: {
      refreshRate: 30,
      retentionDays: 14,
      thresholds: {
        cpu: 80,
        memory: 85
      }
    }
  }
});

Query Servers

// Get all servers in organization
const servers = await findServersByUserId(userId);

Server Removal

Servers with active services cannot be removed. Delete all applications, databases, and compose stacks before removing a server.

// Check for active services
const hasActive = await haveActiveServices(serverId);

if (!hasActive) {
  await deleteServer(serverId);
}

Security Audit

Dokploy can audit security configurations on remote servers:

const audit = await serverAudit(serverId);

Audit Checks

The security audit evaluates:

Firewall (UFW)
SSH Configuration
User Security
Automatic Updates
Fail2Ban

{
  "ufw": {
    "installed": true,
    "active": true,
    "defaultIncoming": "deny"
  }
}

{
  "ssh": {
    "enabled": true,
    "keyAuth": true,
    "permitRootLogin": "prohibit-password",
    "passwordAuth": "no",
    "usePam": "yes"
  }
}

{
  "nonRootUser": {
    "hasValidSudoUser": true
  }
}

{
  "unattendedUpgrades": {
    "installed": true,
    "active": true,
    "updateEnabled": 1,
    "upgradeEnabled": 1
  }
}

{
  "fail2ban": {
    "installed": true,
    "enabled": true,
    "active": true,
    "sshEnabled": "true",
    "sshMode": "aggressive"
  }
}

Monitoring Setup

For cloud deployments, Dokploy automatically configures monitoring:

await setupMonitoring(serverId);

This deploys a monitoring container that:

Collects server metrics (CPU, memory, disk, network)
Monitors container statistics
Sends alerts when thresholds are exceeded
Stores metrics with configurable retention

Monitoring configuration includes refresh rates, retention policies, and alerting thresholds.

Remote Command Execution

Execute commands on remote servers via SSH:

import { execAsyncRemote } from "@dokploy/server";

// Run command on remote server
const output = await execAsyncRemote(
  serverId,
  "docker ps -a"
);

Supported Operating Systems

Dokploy’s setup script supports these Linux distributions:

Debian-based

Ubuntu (LTS)
Debian
Raspbian
Linux Mint
Pop!_OS
Zorin OS

RHEL-based

CentOS
RHEL
Rocky Linux
AlmaLinux
Fedora
Amazon Linux 2
Oracle Linux
OpenCloud OS

Others

Arch Linux
Manjaro
Alpine Linux
SLES
openSUSE Leap
openSUSE Tumbleweed

Best Practices

SSH Key Management

Generate Dedicated Keys

Create separate SSH keys for each server or environment.

Use Key-Only Authentication

Disable password authentication on all servers.

Rotate Keys Regularly

Update SSH keys periodically and remove old keys.

Restrict Key Permissions

Ensure private keys have 600 permissions.

Network Security

Use VPNs or private networks for server communication
Implement firewall rules to restrict access
Enable UFW or iptables on all servers
Use fail2ban to prevent brute force attacks

Resource Planning

Separate build and deploy workloads
Monitor resource usage and scale accordingly
Use dedicated build servers for large projects
Implement backup strategies for all servers

Troubleshooting

Setup Failures

SSH Connection Failed

Symptoms: Cannot connect to server during setupSolutions:

Verify IP address and port are correct
Check SSH service is running: systemctl status sshd
Ensure firewall allows SSH connections
Validate SSH key format and permissions
Test connection manually: ssh -i key.pem user@host

Docker Installation Failed

Symptoms: Docker not installed after setupSolutions:

Check if Snap Docker exists: snap list docker
Verify OS is supported
Review setup logs for specific errors
Install Docker manually and retry
Check available disk space

Port Already in Use

Symptoms: Setup warns about ports 80/443 in useSolutions:

Identify process using port: ss -tulnp | grep ':80'
Stop conflicting service
Configure Traefik to use different ports
Use custom port configuration

Swarm Initialization Failed

Symptoms: Docker Swarm not initializedSolutions:

Check network connectivity
Verify server can detect its public IP
Set ADVERTISE_ADDR manually
Check for existing Swarm membership

Server Status Issues

Inactive Server Status: If a server shows as inactive, it cannot be modified or used for deployments. Remove and re-add the server. Missing SSH Key: Servers require an SSH key assignment. Add an SSH key before running setup. Organization Mismatch: Ensure the server belongs to your active organization to perform operations.

Getting Started

Deployment

Databases

Infrastructure

Advanced

Multi-Server Deployment

Server Types

Deploy Server

Build Server

Server Setup

Requirements

Adding a Server

Server Setup Process

Deploy Server Installation

Build Server Installation

Server Management

Update Server Configuration

Query Servers

Server Removal

Security Audit

Audit Checks

Monitoring Setup

Remote Command Execution

Supported Operating Systems

Debian-based

RHEL-based

Others

Best Practices

SSH Key Management

Network Security

Resource Planning

Troubleshooting

Setup Failures

Server Status Issues

Getting Started

Deployment

Databases

Infrastructure

Advanced

Documentation Index

​Server Types

Deploy Server

Build Server

​Server Setup

​Requirements

​Adding a Server

​Server Setup Process

​Deploy Server Installation

​Build Server Installation

​Server Management

​Update Server Configuration

​Query Servers

​Server Removal

​Security Audit

​Audit Checks

​Monitoring Setup

​Remote Command Execution

​Supported Operating Systems

Debian-based

RHEL-based

Others

​Best Practices

​SSH Key Management

​Network Security

​Resource Planning

​Troubleshooting

​Setup Failures

​Server Status Issues

Server Types

Server Setup

Requirements

Adding a Server

Server Setup Process

Deploy Server Installation

Build Server Installation

Server Management

Update Server Configuration

Query Servers

Server Removal

Security Audit

Audit Checks

Monitoring Setup

Remote Command Execution

Supported Operating Systems

Best Practices

SSH Key Management

Network Security

Resource Planning

Troubleshooting

Setup Failures

Server Status Issues