Guides
Deploy Uptimy Agent on Dokploy
Add the agent to a Dokploy project from the template, sign in with the generated password, and monitor your apps, databases and cron jobs. About five minutes.
Overview
Uptimy Agent is an open-source monitor (Apache-2.0, on GitHub) with its own UI, alert channels and public status page, and no account needed. On your Dokploy server it checks:
- Your apps, at their domains: status code and response time, and a TLS check that warns before a certificate expires.
- Postgres, MySQL, MariaDB and Redis created in Dokploy, over the server's internal network, by logging in and running a query.
- Cron jobs and backups, as heartbeats that alert when a run doesn't check in.
It's a single Go binary that idles at a few MiB of memory, so it fits next to your apps on a small server.
What the template deploys
| Service | A Docker Compose service with one container, uptimy-agent, from ghcr.io/uptimy/agent |
| Volume | uptimy-agent-data, mounted at /data. The agent keeps everything here in one SQLite database: monitors, history, settings and users. |
| Domain | A generated *.sslip.io domain on port 8080, for the UI and the status page at /status. Replace it with your own under Domains. |
| Variables | ADMIN_USERNAME=admin and ADMIN_PASSWORD, 24 random characters generated when you create the service. |
1. Create the service from the template
- In Dokploy, open the project the agent should belong to and click Create Service → Template.
- Search for Uptimy Agent and click Create.
- Open the new service and click Deploy.
The deploy takes under a minute. The container reports healthy once /healthz answers, and the Logs tab shows uptimy-agent listening.
2. Sign in
Open the domain from the service's Domains tab. Sign in as admin with the value of ADMIN_PASSWORD from the Environment tab.
While ADMIN_PASSWORD is set, that password is managed in Dokploy, not in the agent: change the variable and deploy again to set a new one. That's also how you get back in after losing it.
Add the people who need access under Users, as admins or viewers. Each of them can turn on two-factor sign-in under Account.
HTTPS
sslip.io domain is plain HTTP. Before you share the agent, add your own domain under Domains with HTTPS turned on, pointing at the service uptimy-agent on port 8080, and deploy again.3. Add an alert channel
Under Notifications, add a channel: Slack, Discord, Teams, Telegram, email, ntfy, PagerDuty, a webhook, or one of 30+ more through Shoutrrr. New channels alert for every monitor, including the ones you add later, so one channel is all the alerting setup you need.
4. Monitor your apps
Under Healthchecks, add an HTTP check for each app's domain. Use a health path if the app has one, such as /health. The check fails on a wrong status code or a timeout. Add a TLS check on the same domain to hear about an expiring certificate before visitors do.
For a cron job or backup, add a heartbeat under Heartbeats with the job's schedule, and add curl -fsS <ping URL> as the job's last step. The heartbeat's page shows the ping URL.
5. Check your databases
A database created in Dokploy shows an Internal Connection URL on its page. The agent connects to it over Dokploy's internal network, so the database needs no public port. Keep the URL in Dokploy, not in the agent's database:
- In the agent service's Environment tab, add a variable with the internal URL, for example
POSTGRES_URL=postgresql://.... - In the General tab, add the same name to the compose file's environment and deploy again. Dokploy only passes the variables the compose file lists.
- In the agent, add a Postgres check with the target
${POSTGRES_URL}.
environment:
- ADMIN_USERNAME=${ADMIN_USERNAME}
- ADMIN_PASSWORD=${ADMIN_PASSWORD}
- POSTGRES_URL=${POSTGRES_URL}The check logs in and runs a query, so a full connection limit or a rejected password fails it too. MySQL, MariaDB and Redis work the same way.
6. Publish the status page
Under Status page, add the monitors visitors should see. It's public at /status on the agent's domain and never shows targets or internal hostnames. To serve it on a domain such as status.example.com, add that domain to the service under Domains (service uptimy-agent, port 8080), deploy again, and enter it under Status page → Custom domain in the agent. That domain serves only the status page, so sign-in stays on the other one.
Back up the data
Everything the agent knows is in the uptimy-agent-data volume. Dokploy's Volume Backups tab can copy it to S3-compatible storage on a schedule. Redeploying and updating keep the volume.
When the agent itself goes down
A monitor on the same server can't report that the server is down. In the agent, Settings → Uptimy Cloud connects it to a free Uptimy account. The agent uploads its results every minute (every 5 minutes on Free), and Uptimy alerts you from outside when the uploads stop. Its monitors show up in your workspace for status pages, SLA reports and workflows, without counting toward your plan's limits. See Connect to Uptimy Cloud.
Updating
The template pins an agent version. To update, change the image tag in the General tab to a newer release and deploy. The database is migrated on start.
Troubleshooting
- The domain shows 404: Traefik only picks up a domain after a deploy. Deploy again after adding or changing one, and check that it points at port 8080.
- A database check says a variable isn't set: add it to both the Environment tab and the compose file's environment, then deploy again.
- Monitors are gone after a deploy: the volume must stay mounted at
/data. - The admin password doesn't work: it's the current value of
ADMIN_PASSWORD. Set a new one there and deploy again.
Next steps
- Uptimy Agent docs: other installs, importing from Uptime Kuma, and the full reference
- Every check type and heartbeat setting
- Configuration reference: every environment variable, including monitors as code in YAML