Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Nettalco/dokploy/llms.txt

Use this file to discover all available pages before exploring further.

Dokploy lets you manage an entire fleet of servers from a single dashboard. Rather than SSH-ing into each machine manually, you register remote servers in Dokploy, attach an SSH key, and then deploy any application, database, or Docker Compose stack to any server in your fleet — all without leaving the UI.

​
How Multi-Server Works

Your primary Dokploy installation acts as the control plane. When you add a remote server, Dokploy stores its host address, SSH port, and a reference to an SSH key. Every subsequent operation — setup, validation, deployment — is performed by Dokploy over SSH from the primary node to the remote host. Applications and databases created inside Dokploy all carry an optional serverId. When a serverId is present, Dokploy executes Docker commands on the remote host via execAsyncRemote. When no serverId is set, commands run on the local (primary) server.
The multi-server feature requires a valid Enterprise license. The API will return a FORBIDDEN error if you try to list servers for permission-management purposes without a valid license.

​
Adding a Remote Server

1

Open the Servers page

In the Dokploy dashboard, navigate to Settings → Servers, then click Add Server.
2

Enter connection details

Fill in:
  • Name – a friendly label for the server
  • IP Address / Host – the public IP or hostname of the remote VPS
  • Port – SSH port (default: 22)
  • Username – the OS user Dokploy will SSH as (e.g., root or ubuntu)
3

Attach an SSH key

Select an existing SSH key from the drop-down, or create a new one (see SSH Key Management below). The key must already be authorised on the remote server.
4

Validate the connection

Click Validate. Dokploy calls server.validate internally (serverValidate), which checks that all required tools are reachable. The response includes the versions and enabled state of:
ComponentField
Dockerdocker.enabled, docker.version
Rclonerclone.enabled, rclone.version
Nixpacksnixpacks.enabled, nixpacks.version
Buildpacksbuildpacks.enabled, buildpacks.version
Railpackrailpack.enabled, railpack.version
Dokploy networkisDokployNetworkInstalled
SwarmisSwarmInstalled
Main directoryisMainDirectoryInstalled
5

Run server setup

Click Setup Server. This triggers server.setup (calls serverSetup on the backend), which installs Docker, the Dokploy network, and all required tooling on the remote machine. Setup streams logs back to the dashboard in real time via a WebSocket subscription (server.setupWithLogs).

​
SSH Key Management

Dokploy uses SSH key pairs to authenticate against remote servers. Keys are stored per-organisation and can be reused across multiple servers.

​
Generating a key

Use Settings → SSH Keys → Generate (calls sshKey.generate → generateSSHKey). You can choose the key algorithm type. Dokploy returns the private key and the corresponding public key.

​
Adding a key manually

If you already have a key pair, use Add SSH Key and paste the private key. The public key portion is derived automatically. This calls sshKey.create on the backend.

​
Authorising the key on the remote server

Copy the public key and append it to ~/.ssh/authorized_keys on the remote host: 
echo "<your-public-key>" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

​
Key lifecycle

OperationAPI call
List all keyssshKey.all
Read one keysshKey.one
Update keysshKey.update
Delete keysshKey.remove

​
Server Setup

server.setup (internally serverSetup) performs a full provisioning run on the remote host over SSH. It installs:
  • Docker Engine – container runtime
  • Dokploy network – an overlay Docker network used for internal service communication
  • Build tooling – Nixpacks, Buildpacks, Railpack for image building
  • Rclone – used for backup destination access
  • Main Dokploy working directories
Setup logs are streamed back to the dashboard through server.setupWithLogs, a TRPC subscription that emits each log line as it arrives.

​
Server Validation

Run server.validate at any time to confirm that a remote server is correctly configured. The check is non-destructive and returns a structured health snapshot: 
{
  "docker": { "enabled": true, "version": "27.0.3" },
  "nixpacks": { "enabled": true, "version": "1.29.0" },
  "isDokployNetworkInstalled": true,
  "isSwarmInstalled": false,
  "isMainDirectoryInstalled": true,
  "dockerGroupMember": true
}
If any component is missing, re-run Setup Server to reinstall it.

​
Deploying to a Specific Server

When creating an application, Docker Compose stack, or managed database, you will see a Server selector. Choose the registered remote server you want to deploy to. Dokploy stores the serverId on the resource and routes all subsequent deploy, restart, and log operations to that host. You can query which server a resource belongs to at any time via server.one.

​
Build Servers

A server can be designated as a build server (serverType: "build"). Build servers are used exclusively for building Docker images — the resulting image is pushed to a registry and then pulled by the deploy server. This offloads CPU-intensive compilation away from production hosts. Call server.buildServers to retrieve the list of all active build servers associated with your organisation. When creating an application, select a build server to route image builds to that host. Build concurrency per server can be tuned with server.updateBuildsConcurrency.

​
Server Monitoring

Per-server resource metrics are available via server.getServerMetrics. This endpoint fetches time-series data from the monitoring sidecar (see Monitoring): 
// Parameters
{
  url: string;        // monitoring service URL, e.g. http://<ip>:4500
  token: string;      // bearer token for the monitoring service
  dataPoints: string; // number of historical data points to return
}
The response is an array of time-stamped snapshots: 
[
  {
    "cpu": "12.4",
    "cpuModel": "AMD EPYC 7B13",
    "cpuCores": 4,
    "memUsed": "1.2",
    "memUsedGB": "1.2",
    "memTotal": "8.0",
    "diskUsed": "20",
    "totalDisk": "80",
    "networkIn": "0.5",
    "networkOut": "0.3",
    "timestamp": "2024-11-01T12:00:00Z"
  }
]

​
Removing a Server

Before removing a server, all active services running on it must be deleted. Dokploy enforces this via haveActiveServices — if any applications, databases, or compose stacks are still assigned to the server, the removal will be blocked with:
Server has active services, please delete them first
Once the server is empty, call server.remove. Dokploy will:
  1. Audit-log the deletion event
  2. Remove all deployment records associated with the server (removeDeploymentsByServerId)
  3. Delete the server record from the database
Store SSH private keys securely. Anyone with access to the key can connect to your remote servers. Restrict inbound SSH to trusted IPs with a firewall (ufw or cloud security group rules) and consider disabling password-based SSH authentication (PasswordAuthentication no in /etc/ssh/sshd_config). You can audit a server’s security posture from Server → Security (server.security), which checks ufw, SSH configuration, fail2ban, and unattended-upgrades status.

Build docs developers (and LLMs) love

Get started for freeTalk to us