Deployment Lifecycle Management#

Dokploy tracks every deployment execution — whether triggered manually, via webhook, or by a cron schedule — as a row in the deployment table. The lifecycle spans creation, execution, terminal resolution, and, on server restart, automated reconciliation of any interrupted runs.

Deployment Record & Status States#

The deployment schema defines four possible statuses 1:

Each record also stores 2:

• logPath — path to the execution log file
• pid — process ID (set for dokploy-server and server schedule types)
• startedAt / finishedAt — timing metadata
• errorMessage — terminal error detail
• Foreign keys to the owning entity: applicationId, composeId, serverId, previewDeploymentId, scheduleId, backupId, rollbackId, or volumeBackupId

finishedAt is written automatically by updateDeploymentStatus when a deployment reaches a terminal state (done or error).

Deployment Queue (Self-Hosted)#

Self-hosted Dokploy dispatches jobs through a custom in-memory queue — not Redis/BullMQ 3. Key properties:

• Per-partition concurrency — jobs partition by serverId; the local server uses LOCAL_PARTITION 4.
• Per-group FIFO — jobs for the same application or compose project serialize within their group, so the same service never builds in parallel 5.
• DB-driven concurrency limit — resolved at runtime via resolveBuildsConcurrency() from the settings table.
• Cloud bypasses the queue — cloud deployments run directly in the background 3.

The queue is started at boot via startDeploymentWorker() 6 and job processing is handled by processDeploymentJob(), which dispatches to application, compose, or preview deployment handlers.

Cron-Based Schedules#

User-defined recurring schedules are stored in the schedule table and support four target types 7:

Each schedule record stores a cronExpression, optional timezone (defaults to UTC), shellType (bash/sh), command or script, and an enabled flag 8.

scheduleJob() registers each schedule with node-schedule using the schedule's scheduleId as the job name. When a cron fires, runCommand() is invoked, which:

1. Creates a new deployment record via createDeploymentSchedule (status: running) 9
2. Resolves the target container or server and executes the command, streaming output to the logPath
3. Calls updateDeploymentStatus to mark it done or error 10

If a container is not found, the deployment is immediately errored with a descriptive message 11.

For dokploy-server and server schedule types, the PID of the spawned process is parsed from stdout and written back to the deployment record via updateDeployment 12.

Schedules are loaded at startup by initSchedules(), which queries all enabled=true schedules and registers each via scheduleJob(). removeScheduleJob() cancels a specific job by scheduleId.

Startup Reconciliation & Recovery#

Because the queue is in-memory, any deployment in running state when the process exits has no associated worker. On server boot, initCancelDeployments() performs a bulk reconciliation:

1. Sets all status = 'running' deployments → status = 'cancelled' 13
2. Resets applicationStatus → 'idle' for all affected applications 14
3. Resets composeStatus → 'idle' for all affected compose projects 15

This prevents services from remaining stuck in a "deploying" state in the UI after a restart.

The full server startup sequence (self-hosted only) is 16:

initCancelDeployments() ← reconcile stale running deployments
initSchedules() ← register cron jobs from DB
startDeploymentWorker() ← start in-memory queue worker

Note on legacy Redis state: Instances that previously used BullMQ may retain stale bull:deployments:* keys in Redis. These must be cleared manually; initCancelDeployments only reconciles Postgres records, not Redis queue state. See the Core Infrastructure doc for the cleanup commands.

Key Source Files#