Monitoring Dokku Apps with Vigilmon

Dokku is an open-source platform-as-a-service that turns a Linux server into your own private Heroku. With a single git push, it builds and deploys your app in a Docker container with automatic SSL, process management, and zero-downtime deploys. The tradeoff: all of that happens on one machine you own, and there's no managed reliability layer watching it. Vigilmon fills that gap by monitoring your Dokku-deployed app endpoints, SSL certificates, and deploy health from outside the server.

What You'll Set Up

• HTTP uptime monitors for each deployed Dokku app
• Per-app SSL certificate expiry alerts
• Health check endpoint strategy using Dokku's built-in checks
• Cron heartbeat monitoring for Dokku scheduled workers
• Alerting tuned for Dokku's zero-downtime deploy window

Prerequisites

• Dokku v0.30+ on a Ubuntu/Debian VPS
• At least one app deployed and accessible via a domain
• A free Vigilmon account

Step 1: Add a Health Endpoint to Your Dokku App

Dokku's zero-downtime deploy uses a built-in health check system. If your app exposes a /health endpoint that returns 200 OK, Dokku will wait for it to respond before routing traffic to the new container. You get free deploy safety and a Vigilmon-friendly URL.

Add a health route to your app:

Node.js / Express:

app.get('/health', (req, res) => {
  res.json({ status: 'ok', version: process.env.DOKKU_APP_VERSION });
});

Python / Flask:

@app.route('/health')
def health():
    return {'status': 'ok'}, 200

Ruby on Rails:

# config/routes.rb
get '/health', to: proc { [200, {}, ['ok']] }

Configure Dokku to use it:

dokku checks:set myapp wait-to-retire 10
dokku config:set myapp DOKKU_DEFAULT_CHECKS_WAIT=10

Or add a CHECKS file to your repo root:

WAIT=5
TIMEOUT=30
ATTEMPTS=3
/health  ok

Step 2: Monitor Each App Endpoint with Vigilmon

For every Dokku app, add an HTTP monitor pointing at the app's domain:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. URL: https://myapp.yourdomain.com/health.
4. Set Expected HTTP status to 200.
5. Set Expected body contains to ok (matches {"status":"ok"}).
6. Set Check interval to 1 minute.
7. Click Save.

Repeat for each app. Vigilmon's dashboard gives you a per-app uptime view — useful when you're running multiple microservices or side projects on the same Dokku instance.

Step 3: SSL Certificate Expiry Alerts

Dokku integrates with Let's Encrypt via the dokku-letsencrypt plugin. Certificates auto-renew via a cron job, but the renewal can fail silently if your DNS has changed, port 80 is blocked, or the renewal cron isn't running.

Add a certificate monitor for each app domain:

1. Add Monitor → SSL Certificate.
2. Domain: https://myapp.yourdomain.com.
3. Set Alert when certificate expires in less than 30 days.
4. Click Save.

Check that the letsencrypt cron is registered:

dokku letsencrypt:cron-job --add
crontab -l | grep letsencrypt
# @daily /var/lib/dokku/plugins/available/letsencrypt/cron-job

The 30-day Vigilmon alert gives you a window to diagnose and fix renewal failures before the certificate expires.

Step 4: Monitor the Dokku Health Check Plugin

The dokku-health plugin (if installed) exposes per-app health state via a CLI command:

dokku health:check myapp

You can wrap this in a small HTTP server or use a Vigilmon cron heartbeat to confirm the container is healthy beyond what the public endpoint shows. For a lightweight approach, add a cron heartbeat that succeeds only when the container is running:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set interval to 5 minutes.
3. Copy the ping URL: https://vigilmon.online/heartbeat/abc123.
4. Add a cron on your Dokku server:

# /etc/cron.d/dokku-vigilmon
*/5 * * * * root dokku ps:report myapp --format json | grep -q '"running":true' && curl -s https://vigilmon.online/heartbeat/abc123

This signals Vigilmon only when Dokku reports the app's container as running. If the container exits or is in restart-backoff, the ping is skipped and Vigilmon alerts.

Step 5: Alert Tuning for Zero-Downtime Deploys

Dokku's zero-downtime deploy briefly runs two containers in parallel (old and new) and then switches traffic. A naive 1-failure alert rule will fire during every deploy. Tune Vigilmon to absorb this:

1. Open your app's monitor in Vigilmon.
2. Set Consecutive failures before alert to 3.
3. At a 1-minute check interval, this gives Dokku a 3-minute window to complete a deploy before an alert fires — enough for most builds.

For larger apps with long boot times, increase to 5 consecutive failures.

Step 6: Monitor Worker Processes with Cron Heartbeats

Dokku supports worker and clock processes via a Procfile. Background workers don't expose HTTP endpoints, so use Vigilmon's heartbeat monitor:

# Procfile
web: gunicorn myapp.wsgi
worker: celery -A myapp worker
clock: python manage.py runcrons

For each background process, add a heartbeat ping at the end of each task cycle, or use a dedicated health signal:

# At the end of a periodic task
import requests
requests.get('https://vigilmon.online/heartbeat/worker-abc123')

Create a separate Cron Heartbeat monitor in Vigilmon for each worker type so failures are attributed correctly.

Going Further

• Multi-app Dokku server: Tag each Vigilmon monitor with the app name and use status page groups to present per-app uptime to stakeholders or customers.
• Dokku resource limits: If you hit RAM limits, Dokku containers OOM-kill silently. Combine Vigilmon's external check with a server-level memory alert for full coverage.
• Pre-deploy checks: Add a Vigilmon monitor for a staging Dokku app and make it a required check in your CI pipeline before promoting to production.

With Vigilmon watching every Dokku app's health endpoint, SSL certificate, and background worker heartbeat, you get the observability layer that Dokku's self-hosted model doesn't include out of the box — so your side projects and production apps stay up even at 3am.