Docker Swarm Deployment#

Dokploy manages Docker Swarm services for both applications and databases via a unified code path that handles local and remote clusters transparently. The two primary concerns are:

1. Update ordering — whether the old task stops before or after the new task starts, which directly impacts volume lock safety for stateful workloads.
2. Remote cluster management — SSH-based Dockerode connections that let the same deployment code run against a remote Swarm manager without a separate code path.

Key Entry Points#

Update Ordering: stop-first vs start-first#

Docker Swarm's UpdateConfig.Order and RollbackConfig.Order each accept "start-first" or "stop-first":

• start-first — the replacement task is started before the old task is stopped. Provides zero-downtime rolling updates for stateless services.
• stop-first — the old task is fully stopped before the new task starts. Required for services with named volumes, because two tasks cannot hold an exclusive volume lock simultaneously.

Defaults#

generateConfigContainer applies these defaults when no explicit config is stored:

• UpdateConfig: { Parallelism: 1, Order: "start-first", FailureAction: "rollback" } 1
• RollbackConfig: { Parallelism: 1, Order: "start-first" } 2

Volume lock warning: Stateful services (databases, anything with a named volume mount) should override Order to "stop-first" via the UI. Using start-first with an exclusive-access volume will cause the new task to fail on mount while the old task still holds the lock.

Placement constraint for mounted services#

If an application has mounts but no explicit placementSwarm, generateConfigContainer automatically adds Constraints: ["node.role==manager"] 3. This pins stateful services to the manager node and prevents cross-node volume access issues in multi-node clusters.

Configuration schema#

The UpdateConfigSwarm interface defines the full shape:

Parallelism: number
Delay?: number // nanoseconds between updates
FailureAction?: string // "pause" | "continue" | "rollback"
Monitor?: number // nanoseconds to monitor after each task update
MaxFailureRatio?: number
Order: string // "stop-first" | "start-first"

Both updateConfigSwarm and rollbackConfigSwarm are persisted as JSON columns on the applications table 4, typed as UpdateConfigSwarm. The UI exposes these via update-config-form.tsx and rollback-config-form.tsx, each with an Order select field.

SSH-Based Remote Cluster Management#

getRemoteDocker#

getRemoteDocker(serverId?) is the single function that unifies local and remote Dockerode access:

• If serverId is null/undefined or the server has no sshKeyId → returns the shared local docker singleton.
• Otherwise → creates a new Dockerode instance with protocol: "ssh" using the server's ipAddress, port, username, and sshKey.privateKey from the database.

mechanizeDockerContainer calls getRemoteDocker(application.serverId), so the exact same service create/update logic runs whether targeting the local cluster or a remote one over SSH.

Shell-based cluster inspection#

For read-only cluster operations, Dokploy uses execAsyncRemote(serverId, command) (shell over SSH) rather than the Dockerode API 5:

• getSwarmNodes — runs docker node ls --format '{{json .}}'
• getNodeInfo — runs docker node inspect <nodeId>
• getNodeApplications — runs docker service ls --format '{{json .}}'

These are exposed to the frontend via the swarmRouter tRPC endpoints (getNodes, getNodeInfo, getNodeApps, getAppInfos, getContainerStats).

Two SSH transports#

Both resolve the server record via findServerById and authenticate with the stored private key.

Service Create / Update Pattern#

mechanizeDockerContainer follows a try-update-then-create pattern:

1. Attempt update: calls docker.getService(appName), inspects the current Version.Index, then calls service.update({ version, ...settings, ForceUpdate: current + 1 }) 6. Incrementing ForceUpdate triggers a rolling restart even when the spec is otherwise unchanged.
2. Fall back to create: if the service does not exist (or any error occurs), calls docker.createService(settings) 7.

The settings object passed to both paths is assembled from:

• generateConfigContainer(application) → UpdateConfig, RollbackConfig, Placement, Mode, RestartPolicy, HealthCheck, Networks, etc. 8
• calculateResources(...) → CPU/memory limits and reservations 9
• prepareEnvironmentVariables(...) → merged env vars from project, environment, and application layers 10
• getRemoteDocker(application.serverId) → local or SSH Dockerode instance 11