How to Deploy Gatus on a VPS

copystorage:
  type: sqlite
  path: /data/data.db

copystorage:
  type: postgres
  path: "postgres://user:password@127.0.0.1:5432/gatus?sslmode=disable"

#Prepare the server

This guide assumes Docker Engine and the Compose plugin are installed, along with a non-root deploy user and a ufw firewall. If not, work through Docker & Compose on Ubuntu first.

Open SSH and the reverse proxy ports only — Gatus's own port stays internal:

copysudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enable
sudo ufw status verbose

Outbound matters more than inbound on a monitoring box: the checks have to reach what they watch. If your provider filters egress, make sure ICMP is permitted before you write any icmp:// endpoints, or every ping check will report down while the HTTP checks pass.

#Write config.yaml first

Gatus reads its configuration at startup. There is no first-run wizard to fall back on, so the file has to exist before the container does. Create the project directory and write a minimal config:

copymkdir ~/gatus && cd ~/gatus

copycat > config.yaml <<'YAML'
endpoints:
  - name: website
    url: "https://example.com"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 300"
YAML

That is a complete, working configuration: one endpoint, checked every sixty seconds, healthy only when it returns a 200 and answers in under 300 ms. Both conditions must pass for the square to be green.

Now run it, mounting that file in at /config/config.yaml, which is where the image looks:

If you just want to see it work before committing to a compose file, this single command is enough. Stop and remove that container before the compose step below, or the two will fight over the same name and port:

docker run -d --name gatus -p 8080:8080 \
  --mount type=bind,source="$(pwd)"/config.yaml,target=/config/config.yaml \
  ghcr.io/twin/gatus:stable

Load http://SERVER_IP:8080 and you should see one endpoint with its first squares appearing. That's the smoke test — the image runs and your YAML parses. Don't leave it like this (no persistence, port wide open): docker rm -f gatus and move to the real deployment.

#Install Gatus (Docker Compose, with persistence)

Same image, plus the storage block that makes the history real and a loopback bind so the reverse proxy is the only public door:

copycat > docker-compose.yml <<'YAML'
# docker-compose.yml
services:
  gatus:
    image: ghcr.io/twin/gatus:stable
    container_name: gatus
    restart: unless-stopped
    volumes:
      - ./config.yaml:/config/config.yaml:ro
      - gatus-data:/data
    ports:
      # Loopback only — Caddy is the sole route in from outside.
      - "127.0.0.1:8080:8080"

volumes:
  gatus-data:
YAML

Then extend config.yaml with the storage block and a slightly more realistic set of endpoints:

copystorage:
  type: sqlite
  path: /data/data.db

ui:
  title: "Status | example.com"
  header: "example.com"

endpoints:
  - name: website
    group: public
    url: "https://example.com"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 300"
      - "[CERTIFICATE_EXPIRATION] > 168h"

  - name: api-health
    group: public
    url: "https://api.example.com/health"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[BODY].status == UP"

  - name: postgres
    group: internal
    url: "tcp://10.0.0.5:5432"
    interval: 60s
    conditions:
      - "[CONNECTED] == true"

Bring it up and watch the logs for parse errors:

copydocker compose up -d
docker compose logs --tail 50

A few things in that config are worth naming, because they're the parts that make Gatus more than a ping:

• group buckets endpoints on the dashboard. Use it — a flat list of thirty squares tells you nothing at a glance.
• [CERTIFICATE_EXPIRATION] > 168h turns the endpoint red a week before a TLS certificate expires. This is the check that catches the renewal that quietly stopped working, and it costs you one line.
• [BODY].status == UP reads a field out of a JSON response, so a 200-with-an-error-payload still counts as down. A status code alone is a weak health check.
• tcp:// and icmp:// prefixes switch the check type. Only [CONNECTED], [IP] and [RESPONSE_TIME] are available for ICMP endpoints — there's no body or status code to assert on.

#HTTPS + domain

Point an A record for status.example.com at the server's public IP, wait for it to resolve, then terminate TLS in front of 127.0.0.1:8080. The straightforward path is Automatic HTTPS with Caddy:

status.example.com {
    reverse_proxy 127.0.0.1:8080
}

That's the whole thing — Gatus is a plain HTTP service with no WebSocket requirement for the dashboard, so there are no special proxy headers to set.

If you run Caddy as a container, 127.0.0.1 is the proxy's own loopback and won't reach Gatus. Put both services in one compose file and use reverse_proxy gatus:8080, dropping the host port publish entirely.

Gatus can also terminate TLS itself (web.tls.certificate-file / web.tls.private-key-file), but then you own certificate renewal. Let the reverse proxy do it.

#Lock the dashboard down

Here is the second thing that surprises people: a fresh Gatus dashboard is public. Anyone who loads the URL sees every endpoint name, every hostname, and every group you configured — which is a fairly detailed map of your infrastructure. That is intentional (it doubles as a public status page), but it is almost certainly not what you want for a config that includes tcp://10.0.0.5:5432.

Two options, both under security:

Basic auth, for a personal dashboard. The password goes in as a bcrypt hash, base64-encoded — never as plaintext:

copysudo apt install -y apache2-utils
# Produces the bcrypt hash, then base64-encodes it for the config
htpasswd -bnBC 9 "" 'your-password' | tr -d ':\n' | base64 -w 0

copysecurity:
  basic:
    username: "john.doe"
    password-bcrypt-base64: "JDJhJDA5JC..."

Keep the bcrypt cost sensible (around 9). Basic auth verifies the password against the hash on every request, so a very high cost makes the dashboard crawl.

OIDC, the better answer for a team and a natural pair with a self-hosted SSO like Authentik. Set security.oidc with issuer-url, client-id, client-secret, scopes: ["openid"], and a redirect-url that must end in /authorization-code/callback — that path is fixed by the application. allowed-subjects restricts which identities may sign in; leave it empty and anyone your IdP authenticates gets in.

If you genuinely want a public status page, split it: public endpoints with friendly names on one instance, internal hostnames on a separate authenticated one.

#Alerts

A dashboard nobody is looking at is not monitoring. Alerts hang off each endpoint under alerts, and the provider credentials live once under alerting:

copyalerting:
  discord:
    webhook-url: "https://discord.com/api/webhooks/**********/**********"
  slack:
    webhook-url: "https://hooks.slack.com/services/**********/**********"

endpoints:
  - name: website
    url: "https://example.com"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
    alerts:
      - type: discord
        description: "healthcheck failed"
        failure-threshold: 3
        success-threshold: 2
        send-on-resolved: true

The two thresholds are what separate an alert from a nuisance: failure-threshold is how many checks in a row must fail before you're paged (default 3) and success-threshold how many must pass before the incident is marked resolved (default 2). One missed check on a sixty-second interval is noise; three in a row is an incident. Set send-on-resolved: true — an alerting system that tells you things broke but never that they recovered trains you to ignore it.

Wire a second, independent channel for anything that must wake you up — the useful failure mode is the one where your main chat provider is also down. And give cron jobs a heartbeat via external-endpoints: the job gets a token and an expected heartbeat.interval, pushes a success when it finishes, and Gatus alerts when the push doesn't arrive. That is how you find out a nightly backup has been failing for a week.

#Monitoring as code

The payoff for the YAML-only design shows up now. Point GATUS_CONFIG_PATH at a directory instead of a single file and Gatus merges every *.yaml and *.yml inside it — including subdirectories — into one configuration at startup:

copy    environment:
      GATUS_CONFIG_PATH: /config
    volumes:
      - ./config:/config:ro

That lets each service own its own checks in its own file (config/api.yaml, config/db.yaml), so adding monitoring to a new service is a file in a pull request next to the code it watches. Maps deep-merge and lists append; a primitive value may only be defined once across all files, so alerting.slack.webhook-url belongs in exactly one place — define it twice and startup fails rather than silently picking a winner.

Keep the whole directory in git. That's the feature: your monitoring is reviewable, diffable, and restorable.

#Backups

Two things to preserve, and only one of them is precious:

copycd ~/gatus
tar czf gatus-config-$(date +%F).tar.gz config.yaml docker-compose.yml

docker compose stop
docker run --rm -v gatus_gatus-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/gatus-data-$(date +%F).tar.gz -C /data .
docker compose start

Stopping the container gives a clean copy of the SQLite file; Gatus is light enough that a few seconds of downtime costs nothing. (The volume's real name is prefixed with the compose project directory — confirm with docker volume ls.) Copy both archives off the box. If the config is in git the second command is optional: losing the results database costs you history, not capability. Losing the config costs you the whole setup.

#Upgrades

copycd ~/gatus
docker compose pull
docker compose up -d

The stable tag tracks current releases. Because the configuration is a file you own, upgrades are low-drama: the container is replaced, the config and /data are re-mounted, and history survives — provided you set a persistent storage type. On the memory default, every upgrade silently wipes your history. Skim the release notes before a major jump, and back up the database first.

#Troubleshooting

The container starts and immediately exits. Almost always a YAML error or a missing config. Read docker compose logs gatus — Gatus reports the offending key on startup. The usual causes are a mount that landed as a directory because the file didn't exist when the container first ran (delete the stray directory, create the file, recreate the container) and indentation drift under conditions.

Everything shows 100% uptime with no history after a restart. You're on the memory default. Add the storage block and the /data volume from the install section.

Every ICMP endpoint is down, HTTP endpoints are fine. Ping is blocked somewhere. Check the provider's network firewall and ufw first. Current versions send unprivileged pings, but a hardened host or a container runtime can still refuse them — testing with docker compose exec gatus ping -c1 10.0.0.1 tells you quickly which layer is saying no.

A condition never passes and you can't see why. Expand the result — the dashboard shows the condition with the actual values substituted in, which spots [STATUS] == 200 receiving a 301 or a [BODY] path that isn't in the response. Response-time conditions are in milliseconds: [RESPONSE_TIME] < 300 on a cross-continent check fails forever.

Alerts never arrive. Check that a provider block under alerting exists for the type used on the endpoint — an alert of type slack with no alerting.slack is ignored. Then check failure-threshold: 3 failures on a 5-minute interval is fifteen minutes before you hear anything.

#Verification + next steps

You're done when you can: load https://status.example.com over a valid certificate, get prompted for credentials, see your endpoints grouped and green, restart the container and watch the history still be there, then break something on purpose and receive the alert — and the recovery notice — on a real device.

From there: move the config into a directory in git so each service ships its own checks, add a [CERTIFICATE_EXPIRATION] condition to every HTTPS endpoint you own, and give every cron job a heartbeat. For CPU and memory graphs rather than up/down you want a different tool — Beszel for machine metrics, Grafana for a full metrics stack. For the ranked host picks, see Best VPS for Monitoring & Uptime.