How to monitor a Dokploy deployment
Dokploy shows whether your containers are running, not whether your apps work. How to add a health check so deploys don't cause downtime, and what to monitor from outside.
Dokploy is a self-hosted PaaS. It builds your app, runs it in a container, and puts it behind Traefik with a Let's Encrypt certificate. The dashboard shows whether each container is running. A running container doesn't mean a working app, though. The app inside can be failing on every request, stuck on a migration, or unable to reach its database, and the container still shows as running.
Health checks and deploys
This one matters before monitoring even comes in. Dokploy runs applications as Docker Swarm services, and by default a new deploy stops the running container and starts the new one. Dokploy's docs point out that this leads to Bad Gateway errors while the new container is starting.
The fix is a health check in the application's Swarm settings. With one in place, Dokploy waits for the new container to pass before switching over. This is the example from Dokploy's docs, for an app on port 3000:
{
"Test": ["CMD", "curl", "-f", "http://localhost:3000/health"],
"Interval": 30000000000,
"Timeout": 10000000000,
"StartPeriod": 30000000000,
"Retries": 3
}The durations are in nanoseconds, so 30000000000 is 30 seconds. The check runs inside the container, so curl has to be installed in the image.
What to monitor
Each app by its public domain. If you run a frontend, an API and a docs site on Dokploy, each has its own domain and can fail on its own. Give each one a monitor.
HTTPS, not HTTP. Monitoring the HTTPS URL tests the certificate and Traefik's TLS setup along with the app.
Health endpoints over the root path. GET / on a frontend can return 200 while the backend behind it is down. A health endpoint that checks the database and other dependencies, and returns an error status when one fails, tells you much more. If you're on Elixir, I wrote about a minimal health check plug for Plug and Phoenix.
Dokploy-specific things to know
Routing. For applications, Dokploy writes a Traefik configuration file per domain, and changes apply without a redeploy. For Docker Compose services, domains are Traefik labels on the containers, and changes need a redeploy. Either way, if the routing is wrong, the container runs while requests to the domain get a 404 from Traefik or reach the wrong service. An external check sees the same response your users do.
Certificate renewal. Traefik gets and renews Let's Encrypt certificates automatically. Renewal fails if your DNS no longer points at the server, or if a CAA record on the domain doesn't allow Let's Encrypt. The certificate keeps working until it expires. Larm checks certificate expiry on every HTTPS monitor and alerts at 28, 14, 7 and 1 days before it runs out.
Memory limits. If you set a memory limit on a container and the app goes over it, the container is killed and restarted. An app that keeps going over its limit restarts over and over and never stays up long enough to serve requests.
Shared resources. Apps on the same server share its CPU, memory and disk. One app using too much of any of them slows down or breaks the others. A monitor per app shows you which one stopped responding first.
Setting it up in Larm
Create an HTTP monitor in Larm for each app's public domain.
Timeout. Larm's default is 10 seconds. Containers on Dokploy stay running, so there's no cold start to allow for.
Keywords. If your health endpoint returns JSON, add an expected keyword from a healthy response. The check then fails when the endpoint returns 200 with a problem in the body.
Check interval. 1-minute checks for anything user-facing, on Pro. The free plan checks every 3 minutes, which is fine for staging and internal tools.
The server itself. A TCP monitor on port 443 tells you the server is accepting connections. Together with an HTTP monitor per app, that tells you whether a failure is one app or the whole server. If the server is on Hetzner, the Hetzner guide covers the server side.
Larm's free plan includes 15 monitors, enough for a Dokploy server running several apps.
Start monitoring in minutes.
Free plan. 15 monitors. Multi-probe voting. No credit card.
Sign Up Free