Gatus

Monitor endpoint conditions and publish a status page with persistent history.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Gatus

Monitor endpoint conditions and publish a status page with persistent history.

The native deployment creates files/gatus.yaml, mounted at /config/config.yaml, with persistent SQLite storage in /data.
Edit endpoints as a JSON array through Native settings or edit the portable YAML directly. Each endpoint can define its URL, interval and conditions.

Customize deployment inputs (1)

Local HTTP port port: portDefault: 18082

Save this as inputs.json and adjust the values before initialization.

{
  "port": 18082
}

selfhost app --directory ./gatus init gatus --method native --inputs inputs.json

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./gatus start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd gatus
docker compose -f compose.yaml up -d

Review the portable Compose and native configuration before starting.
The default listener is local-only. Add an authenticated HTTPS proxy before exposing private data.
Edit endpoint conditions, alerts, authentication and storage in App settings. Native YAML remains portable.

Before configuring integrations

Configure alerting providers, external endpoints, UI buttons and tunneling using their native structured configuration.
Basic authentication and OIDC are available in the native configuration. The issuer, client, callback and permitted subjects must match your provider.
Storage can use SQLite or an explicitly configured PostgreSQL connection.
Selfhost does not provision a Gatus OIDC client or PostgreSQL database automatically through this profile.
Alert provider credentials and custom endpoint URLs must be supplied by the operator.

Gatus integrations

Compose service: gatus. These operations use the profile saved when this deployment is created.

OIDC allowed-subjects must explicitly restrict access if the provider serves other users. Empty allowed-subjects permits all authenticated subjects.
Endpoint, alert and tunnel JSON can contain secrets. Prefer configuration-file environment substitutions and private network connections.

Native settings

Changes use the app’s native YAML file. Unrelated settings are preserved.

Supported fields (27)

metrics metrics: boolean · advanced
ui / title ui-title: string · advanced
ui / description ui-description: string · advanced
ui / header ui-header: string · advanced
ui / logo ui-logo: string · advanced
ui / link ui-link: string · advanced
ui / buttons ui-buttons: json · advanced
ui / dark-mode ui-dark-mode: boolean · advanced
endpoints endpoints: json · advanced
external-endpoints external-endpoints: json · advanced
alerting alerting: json · advanced
tunneling tunneling: json · advanced
storage / type storage-type: string · advancedChoices: sqlite, postgres, memory
storage / path storage-path: secret · advanced
storage / caching storage-caching: boolean · advanced
security / basic / username security-basic-username: string · advanced
security / basic / password-bcrypt-base64 security-basic-password-bcrypt-base64: secret · advanced
security / oidc / issuer-url security-oidc-issuer-url: string · advanced
security / oidc / redirect-url security-oidc-redirect-url: string · advanced
security / oidc / client-id security-oidc-client-id: string · advanced
security / oidc / client-secret security-oidc-client-secret: secret · advanced
security / oidc / scopes security-oidc-scopes: string_list · advanced
security / oidc / allowed-subjects security-oidc-allowed-subjects: string_list · advanced
security / oidc / session-ttl security-oidc-session-ttl: string · advanced
web / port web-port: integer · advancedRange: 1 to 65535
web / tls / certificate-file web-tls-certificate-file: string · advanced
web / tls / private-key-file web-tls-private-key-file: string · advanced

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./gatus config gatus
selfhost app --directory ./gatus plan gatus changes.json
selfhost app --directory ./gatus apply gatus changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

gatus: twinproduction/gatus:v5.37.0

v5.37.0 twinproduction/gatus:v5.37.0
Local Docker HTTP startup, native configuration roundtrip, declared read-only actions and container recreation with persistent volumes passed. Native file bytes used a fixture volume because this host did not share bind directories; host file sharing remains unverified. External provider login and version upgrades require separate validation.

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Gatus documentation