Docker Compose
Use the product’s Compose file. It includes loopback networking, a named volume and documented configuration options. It runs :edge; change the tag to pin the candidate.
QUICK START
From zero to
your first glance.
One container. A browser. Something worth keeping an eye on.
Let’s get your own SubGlance running.
These instructions pin the current release candidate, v0.1.0-rc7. Releases on GitHub list what changed.
Give it a place to live.
With Docker installed and running, paste this into your terminal. The named volume keeps the SQLite database between container restarts.
Docker
docker run -d -p 127.0.0.1:8080:8080 -v subglance:/data ghcr.io/frankgraave/subglance:0.1.0-rc7Start on loopback.
Keep 127.0.0.1: in the port mapping. The first person to reach the dashboard creates the administrator account. For a remote server, use an SSH tunnel or a reverse proxy you control to reach setup.
The image tag pins this release candidate, so it will not change under you. The :edge image follows development instead. The image is signed, and release candidates are also distributed as signed binary archives. Verify the image
Meet your new dashboard.
Open http://localhost:8080/. Enter your email and a password of at least 12 characters to create the first administrator. There’s no default account or password.
The setup screen closes once an account exists. Your next visit brings you to sign-in.
What should we watch?
Choose Add a monitor, paste your site or API address, and use Test it to check reachability before saving. Your monitor starts grey, then shows the result when its first check lands.
Your first websiteHTTP(S) · status, latency, keyword checks
Need something else? Use TCP for an open port, ping for a host, SSL for a certificate, DNS for a record, domain for a registration’s expiry date, or push for a job that reports back to you.
How do I monitor a private or local service?
Private targets are blocked by default. If you intend to monitor your internal network, add -e SUBGLANCE_ALLOW_PRIVATE_TARGETS=true before the Docker image name. The instance can then reach private targets, so grant dashboard access accordingly.
A router or NAS with a self-signed certificate? When Test it fails on that certificate, the form offers to trust it for that monitor. For a private CA, point --extra-ca-file at its certificate to trust it for the whole instance. Certificates of your own
How do I watch a nightly backup?
Create a push monitor and save the secret push URL when it is shown. Call it only after a successful job, or include the job’s exit status. A check-in proves the script reached that line; it does not verify your backup’s contents.
Push check-in
restic backup /data && curl -fsS "$PUSH_URL"Make sure the alert reaches you.
Open Notifications and configure a webhook, Discord, Slack, Telegram, email, ntfy, Gotify or SMS channel, then send a test message. Choose it under Channels when you add or edit a monitor.
By default, two consecutive failures confirm an incident. Alerts wait up to 90 seconds for grouping; change --alert-group-window to 0 if you prefer immediate delivery after confirmation.
Docker isn’t the only way.
A single binary
Linux and macOS on amd64 or arm64. Windows on amd64. The dashboard is included. Verify the signature and checksums before running.
Download and verifyPrefer building from source? The installation guide covers Go, the dashboard and the full build.
A few things to set up next.
- Protect channel credentials. Set a secret key to encrypt notification configuration at rest. Without it, webhook URLs, bot tokens and SMTP passwords are plaintext in the database.
- Back up the database properly. Use the
subglance backupcommand for a consistent backup while running. Copying the live database file alone misses WAL data. - Watch the watcher. An optional external watchdog can alert when SubGlance itself stops reporting.
- Know its one outbound check. Before it confirms an outage on a network error, SubGlance dials two public DNS resolvers,
1.1.1.1:53and9.9.9.9:53, over TCP, to tell its own lost connection from a real outage; it does so once at start too. When a check’s own lookup gets no answer, it also asks your resolver for two reference names. Choose other targets or turn it off in the configuration or on the Settings page, and other names in the configuration. - Let alerts link back. Set
--base-url(SUBGLANCE_BASE_URL) to the address SubGlance is reached at, path prefix included. Every alert then links to its incident and its monitor, and an alert about an open incident carries a link that mutes its repeat alerts. - Schedule maintenance. A planned deployment should not page anyone. Schedule a one-off or weekly window per monitor or tag from the Monitors page; checks continue, alerts pause.