Preview Deployment Management#

Preview deployments give every GitHub pull request its own isolated Docker service and Traefik-routed URL. Each preview is a child of a parent application (configured with isPreviewDeploymentsActive = true) and lives in the preview_deployments table 1. Its appName follows the pattern preview-{parentAppName}-{6-char random suffix} 2.

Key source files:

Creation via GitHub PR Webhook#

The webhook handler at /api/deploy/github processes pull_request events. After verifying the HMAC-SHA-256 signature 3, it dispatches on action:

• opened / synchronize / reopened / labeled — creates or re-uses an existing preview deployment and enqueues a deploy job 4.
• closed — calls removePreviewDeployment() for every preview tied to the PR's pullRequestId 5.
• unlabeled — recognized but skips shouldCreateDeployment; no new build is triggered 6.

Security gate: Before creating a deployment, the handler checks previewRequireCollaboratorPermissions. If enabled (the default), it calls checkUserRepositoryPermissions for the PR author. Unauthorized authors are blocked and a security comment is posted to the PR 7.

Preview limits and label filters: If previewLabels is configured, the PR must carry a matching label. If the current preview count exceeds previewLimit, the app is skipped 8.

createPreviewDeployment() flow 9:

1. Generates a unique appName (preview-{parent}-{6-char random}).
2. Resolves a wildcard domain from application.previewWildcard (defaults to *.sslip.io). For sslip.io, it embeds the server IP, e.g. preview-myapp-abc123-1-2-3-4.sslip.io 10.
3. Posts an "initializing" comment to the GitHub PR via Octokit 11.
4. Inserts the preview_deployments row, creates the domain record, and calls manageDomain() to write the Traefik YAML config 12.

The deploy job uses applicationType: "application-preview" and carries the previewDeploymentId, distinguishing it from regular application deploys 13.

Cleanup: Preview Deletion#

removePreviewDeployment(previewDeploymentId) runs five cleanup operations sequentially. Each step is wrapped in its own try/catch so a failure in one does not abort the rest 14:

1. Docker service — removeService(appName, serverId) runs docker service rm <appName> locally or over SSH.
2. Deployment logs — removeDeploymentsByPreviewDeploymentId() deletes associated deployment log records.
3. Source code — removeDirectoryCode(appName, serverId) runs rm -rf on the app's code directory under APPLICATIONS_PATH.
4. Traefik config — removeTraefikConfig(appName, serverId) deletes {DYNAMIC_TRAEFIK_PATH}/{appName}.yml. Because Traefik's file provider runs with watch: true, the router disappears without a Traefik restart.
5. DB record — deletes the preview_deployments row 15.

Orphan risk: The parent applicationId foreign key uses onDelete: "cascade" 16, so deleting the parent application removes the DB rows automatically. However, the Docker service and Traefik config file are not deleted by the cascade — they must be cleaned up by explicit code.

Parent Application Deletion and Orphan Cleanup#

When a parent application is deleted via the application.delete tRPC mutation, the handler:

1. Deletes the DB row first 17. This cascades and removes all child preview_deployments rows via the DB FK, but leaves Docker services and Traefik files on disk.
2. Runs its own cleanup chain for the parent only: deleteAllMiddlewares, removeDeployments, removeDirectoryCode, removeMonitoringDirectory, removeTraefikConfig, removeService 18.
3. Does not call removePreviewDeployment() for each child preview before deleting the parent.

This means if a parent application is deleted while preview deployments still exist, their Docker services and Traefik {previewAppName}.yml files become orphaned on the host. The DB rows are gone (cascade), so there is no Dokploy-managed way to clean them up after the fact — manual docker service rm and file deletion are required.

To avoid orphans, explicitly delete or close all associated PRs (which triggers the closed webhook path) before deleting the parent application.

Race Condition Considerations#

Two overlapping async operations can collide during preview cleanup:

1. Concurrent webhook close events. If GitHub sends multiple closed webhook calls for the same PR (e.g. retries), each will call removePreviewDeployment() for the same previewDeploymentId. The first call succeeds; the second call hits findPreviewDeploymentById which throws NOT_FOUND 19, causing the outer TRPCError with BAD_REQUEST to be returned. The webhook handler catches per-preview errors and continues 20, so duplicate events are safe.

2. Active build during deletion. If a deploy job is still running when the parent app is deleted, the queue is cleared immediately via cleanQueuesByApplication (non-cloud only) before the cleanup chain starts 21. In cloud mode, the in-flight deployment is not proactively cancelled before resource removal; a concurrent build could write files or start a container that the cleanup then misses.

3. Docker daemon busy. The broader Docker cleanup utilities use dockerSafeExec() 22, which polls ps aux before executing to avoid race conditions with concurrent Docker operations. This guard applies to bulk cleanup commands (cleanupAll), not to the individual removeService calls in preview deletion.