Dokploy Best Practices

Apply these rules when deploying or reviewing applications, databases, Docker Compose stacks, domains, or infrastructure managed by Dokploy.

Dokploy is a self-hostable PaaS that orchestrates Docker Swarm behind a Traefik reverse proxy, with a PostgreSQL + Redis control plane and a Next.js UI. Most behaviors (zero downtime, rollbacks, domains) are thin wrappers over Swarm and Traefik primitives — understanding both explains most pitfalls.

Core mental model

• A Service is one app/database/compose stack. Services live in an Organization → Project → Environment → Service hierarchy. Use Environments (production, staging) for isolation; never mix prod and staging in one environment.
• Variables cascade: project → environment → service, each level overriding the last. Put shared secrets at project level, stage-specific values at environment level. Reference with ${{project.VAR}}, ${{environment.VAR}}, ${{VAR}}.
• Applications route via Traefik file provider (hot-reload, no redeploy for domain changes). Docker Compose / templates route via Traefik labels (redeploy required for any domain change). This single distinction explains most "domain not working" 404s.

Golden rules

1. Never build on the production server for real workloads. Nixpacks/Buildpack builds are RAM/CPU heavy and can freeze the server. Build + push images in CI/CD (or a dedicated build server) and deploy by image. See deployment-and-builds.md.
2. Listen on 0.0.0.0, not 127.0.0.1. The #1 cause of Bad Gateway, especially Vite/ Astro/Vue. Match the domain's container port to the app's real port.
3. Zero downtime needs a health check + start-first. Without a /health endpoint and Swarm update config, Swarm stops the old container before the new one is ready → Bad Gateway.
4. Persist data in named volumes or ../files, never absolute host paths. Absolute paths and repo-relative mounts get wiped on each git clone redeploy. Only named volumes can be backed up by Volume Backups.
5. Use expose, not ports, for domain-routed Compose services. ports publishes to the host and causes conflicts; Traefik routes over the internal network.
6. Harden the host: Docker bypasses UFW. Container-published ports stay public despite UFW. Use ufw-docker or the VPS provider firewall.

Quick reference

Server & install baseline

• Minimum 2 GB RAM / 30 GB disk; more if you build on the server. Ports 80, 443, 3000 must be free (install fails otherwise). Supported: Ubuntu/Debian, Fedora, CentOS.
• Install: curl -sSL https://dokploy.com/install.sh | sh. Pin versions with DOKPLOY_VERSION. Update with ... | sh -s update.
• Secure before exposing: configure a domain with HTTPS, then disable ip:port access via docker service update --publish-rm "published=3000,target=3000,mode=host" dokploy.
• Avoid disk exhaustion (causes DB recovery mode / UI lockout): schedule docker system prune jobs and enable Docker Cleanup.

When stuck

Most failures fall into a few buckets — domain/Traefik, mounts, Swarm health, or disk. See the Troubleshooting section of platform-ops-security.md for symptom → cause → fix tables (Bad Gateway, 404 on compose/templates, empty mounts, UI inaccessible, Swarm init failure).

References

• deployment-and-builds.md — build types, production CI/CD, zero downtime, rollbacks, preview deployments, auto-deploy, patches, watch paths.
• domains-and-traefik.md — domain management, HTTPS/certificates, internal/strip path middlewares, www redirects, Traefik internals.
• docker-compose.md — Compose vs Stack, isolated deployments, manual Traefik labels, volumes, private registries.
• databases-backups-storage.md — databases, DB backups, volume backups, full-instance backups, S3 destinations, registries.
• platform-ops-security.md — multi-tenancy, variables, remote/build servers, scheduled jobs, server security, troubleshooting.