Resource Cleanup and Lifecycle Management#

Overview#

Dokploy's teardown paths follow a common pattern: the database row is deleted first, sometimes triggering FK cascades that remove child rows, and then infrastructure cleanup (Docker service removal, Traefik config file deletion, source code removal) is attempted for the directly-deleted resource only. Cleanup steps run sequentially in individual try/catch blocks — failures are silently swallowed and never roll back the DB delete. FK cascades that remove child DB rows do not trigger infrastructure cleanup for those children, making parent-level deletions the primary source of orphaned Docker services and Traefik config files.

Application Deletion#

Entry point: application.delete tRPC mutation

The delete handler runs in this order:

1. DB delete first — removes the applications row, which FK-cascades to child preview_deployments, domains, and deployment records 1. Child infrastructure is not cleaned up by the cascade.
2. Queue drain (non-cloud only) — cleanQueuesByApplication() clears pending/active jobs before infrastructure teardown 2. In cloud mode, in-flight builds are not cancelled.
3. Infrastructure cleanup chain — six operations, each independently try/catch'd with errors silently swallowed 3:
   • deleteAllMiddlewares — removes Traefik middleware config entries
   • removeDeployments — clears deployment log records
   • removeDirectoryCode(appName, serverId) — rm -rf {APPLICATIONS_PATH}/{appName}
   • removeMonitoringDirectory — removes monitoring data
   • removeTraefikConfig(appName, serverId) — deletes {DYNAMIC_TRAEFIK_PATH}/{appName}.yml
   • removeService(appName, serverId) — docker service rm <appName>

Orphan risk: Any preview deployments attached to the application have their DB rows cascade-deleted, but their Docker services and Traefik YAML files are not cleaned up because removePreviewDeployment() is never called for each child 4.

Preview Deployment Deletion#

Entry point: removePreviewDeployment(previewDeploymentId)

Triggered automatically by the GitHub pull_request.closed webhook, or callable directly. Five cleanup steps run sequentially with per-step try/catch 5:

1. removeService(appName, serverId) — docker service rm
2. removeDeploymentsByPreviewDeploymentId() — deployment log records
3. removeDirectoryCode(appName, serverId) — source code directory
4. removeTraefikConfig(appName, serverId) — Traefik YAML file ({appName}.yml)
5. DB row delete — removes the preview_deployments record (the associated domain record is removed via FK cascade)

The associated domain DB record has a previewDeploymentId FK with onDelete: "cascade" 4, so deleting the preview row also removes the domain row — but the Traefik YAML is only removed by step 4 above.

Parent application deletion gap: When a parent application is deleted, the DB cascade removes all child preview_deployments rows but removePreviewDeployment() is never called, leaving orphaned Docker services and Traefik YAML files for every preview that existed 4. Manual cleanup requires docker service rm <previewAppName> and deletion of /etc/dokploy/traefik/dynamic/<previewAppName>.yml on the host.

Domain Deletion#

Entry point: domain.delete tRPC mutation

The handler deletes the DB row via removeDomainById() 6, then conditionally cleans up Traefik config:

• Regular application domains — calls removeDomain(application, domain.uniqueConfigKey), which loads the existing {appName}.yml, removes the specific router/service keys for this domain's uniqueConfigKey, and either rewrites the file (if other domains remain) or deletes it entirely (if this was the last router) 7.
• Compose domains — no Traefik cleanup is triggered 8. Compose routing is injected as Docker labels into the compose YAML, not as a per-app YAML file; the label config persists until the next redeploy rewrites it.
• Preview domains — domain record is removed by FK cascade when the preview deployment is deleted; the domain.delete mutation handles per-app removal only if domain.applicationId is set.

ACME certificates: No Dokploy code path removes entries from Traefik's acme.json. When a domain is deleted, Traefik stops routing to it (once the YAML is updated) and eventually stops renewing the cert, but the entry in acme.json persists indefinitely 9. Manual pruning requires editing acme.json and restarting Traefik.

Project and Organization Deletion#

Both paths are DB-only — no infrastructure cleanup code runs at any level.

Project delete 10: Calls deleteProject() 11, which issues a simple DB delete. FK cascades propagate through environments → applications, databases, compose services, and project tags — removing all DB records. Running Docker services, Traefik config files, and source code directories for every service in the project are left untouched.

Organization delete 12: DB delete only, gated by a check that the user retains at least one owned organization. Cascades to projects, servers, members, and invitations. Same infrastructure orphan problem as project delete, compounded by also orphaning any servers registered to the org.

To avoid orphans, delete all services individually (triggering application.delete / compose.delete / database delete for each) before deleting the project or organization.

Orphaned Resource Reference#

Manual cleanup commands for orphaned resources:

• Docker service: docker service rm <appName>
• Traefik config: rm /etc/dokploy/traefik/dynamic/<appName>.yml
• Source code: rm -rf /etc/dokploy/applications/<appName>
• ACME: edit /etc/dokploy/traefik/dynamic/acme.json, remove the domain entry, restart Traefik

Key Source Files#