Getting Started
Perch puts your whole stack on one pane: live host metrics, Docker stats, and HTTP health checks, all self-hosted and yours. This guide gets your first host streaming in just a few minutes.
How Perch fits together
Perch runs as three Docker containers: the hub (your dashboard + API), an agent (collects metrics on the host it runs on), and a Postgres database. Got more machines to watch? Drop an agent on each one and it shows up in the dashboard within seconds of connecting.
Choose a deployment method
Perch runs on Docker, so pick whichever style suits you. They all land you at the same dashboard.
Docker Compose
RecommendedThe simplest path. Works on any single host.
Docker Swarm
For multi-node clusters that need to scale out.
Portainer
If you’d rather drive it all from a GUI.
Your first host
The quickest way in is Docker Compose. The full .env and compose file live in the Compose guide, or you can generate your own with the setup configurator.
Start the stack
From the folder that holds your compose.yaml and .env, bring everything up:
docker compose up -dThe hub, its agent, and Postgres all start together. Migrations run on hub startup on their own, so there’s nothing extra to do here.
Sign in
Open http://your-server:8484 and sign in with the admin email and password you set during setup.
Watch it report
You’ll land on the Overview page. The agent running next to the hub is already reporting, so your host metrics and containers fill in within seconds. No need to refresh either; the dashboard updates live over a WebSocket.
Add more hosts whenever
Want to watch another machine? Run an agent on it and point it at the hub. It joins the dashboard on its own, with no per-host config to babysit.
After deploying
Now that the dashboard is live, wire up whatever you need:
Health checks
Keep an eye on uptime and latency for your HTTP endpoints.
Alerts
Hear about outages on Discord, Slack, or ntfy.
Status pages
Share your uptime publicly with custom domains and themes.
SSO
Let your team sign in without juggling another password.
Upgrading
Upgrading Perch is the same on every deployment method: pull the new images and restart. Database migrations run on hub startup automatically, so you don’t have to think about them.
docker compose pull
docker compose up -dNote
Your specific deployment guide has the exact upgrade commands and any version-specific notes, so check there if you’re on Swarm or Portainer.
Kubernetes & Podman
Right now Docker is the only platform Perch actually collects from. Kubernetes, Podman, Proxmox, Nomad, and LXC/LXD all show up in the UI as Coming soon , so stick with Docker for now.