Dokploy Core Infrastructure#

Overview#

Dokploy's core infrastructure consists of three internal services — Redis, Postgres, and Traefik — provisioned as Docker Swarm services or standalone containers on the host. All join a single overlay network named dokploy-network for DNS-based service discovery 1. Redis provides job queue persistence; Postgres is the application database; Traefik is the reverse proxy/TLS terminator.

The infrastructure is bootstrapped in two phases:

1. Install time — install.sh creates the Swarm, network, secrets, and base services.
2. Application boot — setup.ts (run inside the dokploy container on every start) idempotently reconciles each service's Docker Swarm spec.

Install Script (install.sh)#

Source: apps/website/public/install.sh

The canonical install command is curl -sSL https://dokploy.com/install.sh | sh. The script performs these steps in order 2:

1. Preflight — asserts root, Linux, and that ports 80, 443, 3000 are free 3.
2. Docker install — installs Docker 28.5.0 via get.docker.com; holds packages with apt-mark to prevent unintended upgrades 4.
3. Swarm init — calls docker swarm init --advertise-addr <ip>; auto-detects IP from private interface, falling back to public IP 5. Custom CIDR and extra swarm args can be passed via DOCKER_SWARM_INIT_ARGS 6.
4. Network — creates dokploy-network as an attachable overlay 7.
5. Secrets — generates random credentials with openssl rand and stores them as Docker Secrets (dokploy_postgres_password, dokploy_auth_secret) 8.
6. Postgres service — docker service create ... postgres:16 with the dokploy-postgres volume mounted at /var/lib/postgresql/data 9.
7. Dokploy app service — docker service create ... dokploy/dokploy:<VERSION> with Docker socket and /etc/dokploy bind-mounted 10.
8. Traefik — started as docker run --restart always traefik:v3.6.7 and then attached to dokploy-network via docker network connect 11.

Proxmox LXC is auto-detected and --endpoint-mode dnsrr applied to services; can also be forced via ENDPOINT_MODE=dnsrr 12.

Updating reuses the same script with sh -s update, which calls docker service update --image <new_image> dokploy 13.

Key evolution:

• Volume names were renamed in PR #3032 14 from opaque names (redis-data-volume) to descriptive names (dokploy-redis, dokploy-postgres); the install script was updated to match in PR #89 15.
• LXC --endpoint-mode dnsrr support was added in PR #109 16.

Application Boot: setup.ts#

Source: apps/dokploy/setup.ts

This script runs inside the Dokploy container before the main server process and idempotently provisions each service. It tries to update existing services first; if not found, creates them. The sequence is 17:

setupDirectories()
createDefaultMiddlewares()
initializeSwarm()
initializeNetwork()
createDefaultTraefikConfig()
createDefaultServerTraefikConfig()
docker pull traefik:v<TRAEFIK_VERSION>
initializeStandaloneTraefik()
initializeRedis()
initializePostgres()

Key setup files in packages/server/src/setup/:

All three internal services are pinned to manager nodes (node.role==manager) and join dokploy-network 18 19.

Redis in development: Port 6379 is published in host mode only when NODE_ENV === "development" 20. Production Redis is not exposed on any host port.

Server Runtime Boot: server.ts#

Source: apps/dokploy/server/server.ts

After setup, the main server performs its own initialization chain on startup (lines 61–76), only for self-hosted (non-cloud) deployments:

1. createDefaultMiddlewares() — writes Traefik middleware YAML
2. initializeNetwork() — ensures dokploy-network exists
3. initCronJobs() — Docker cleanup and backup cron schedules
4. initSchedules() — user-defined recurring schedules from DB
5. initCancelDeployments() — resets any status=running deployments from before the restart 21
6. initVolumeBackupsCronJobs() — volume backup schedules
7. sendDokployRestartNotifications() — notifies configured channels
8. startDeploymentWorker() — starts the in-memory deployment queue worker (dynamically imported)

Deployment Queue#

Sources: queueSetup.ts, in-memory-queue.ts, deployments-queue.ts

Dokploy uses a custom in-memory queue (not BullMQ/Redis) for deployment jobs in self-hosted mode 22. The queue design:

• Per-partition concurrency — jobs are partitioned by serverId; the local server uses the LOCAL_PARTITION key. Each partition runs up to concurrency jobs simultaneously 23.
• Per-group FIFO — jobs for the same application or compose project never run in parallel; they serialize within their group 23.
• Concurrency is DB-driven — resolved via resolveBuildsConcurrency() from the settings table 24.
• Cloud uses a no-op queue — cloud deployments run directly in the background, bypassing the queue entirely 22.

The redis-connection.ts file defines a redisConfig pointing to host dokploy-redis (or REDIS_HOST env var) but is a legacy artifact; the in-memory queue does not use it. BullMQ (5.67.3) remains in package.json but the deployment queue has migrated away from it.

Stuck queue workaround: If a deployment is stuck in running state (e.g., after an OOM kill), the in-memory queue state is lost when the process exits. On instances that previously used BullMQ, legacy Redis keys (bull:deployments:*) may still be present and must be cleared manually 25 26:

TASK_ID=$(docker exec $(docker ps -q -f name=dokploy-redis) redis-cli LRANGE 'bull:deployments:active' 0 -1 | head -1)
docker exec $(docker ps -q -f name=dokploy-redis) redis-cli LREM 'bull:deployments:active' 0 "$TASK_ID"
docker exec $(docker ps -q -f name=dokploy-redis) redis-cli DEL "bull:deployments:$TASK_ID"

A UI option "Clean all deployment queue" was added in PR #3625 but only cancels pending jobs; orphaned active jobs may still require a service restart or manual cleanup 26. On server restart, initCancelDeployments() resets any remaining status=running records in Postgres 21.

Health Checks & Admin Controls#

The checkInfrastructureHealth tRPC procedure queries Postgres, Redis, and Traefik health and is exposed in the admin settings UI 27. Redis and Postgres health are verified by exec-ing redis-cli ping and pg_isready inside the running containers 28.

Services can be restarted from the admin settings UI via reloadServer, reloadTraefik, and reloadRedis tRPC mutations 27. These are no-ops on Dokploy Cloud.

Key File Index#