STACKTRA
DEEN

Docs

Installation

You need a Linux server (x86-64 or ARM64) with Docker and the Compose plugin, a domain pointing to the server, free ports 80 and 443 and about 2 GB of RAM.

  1. Add a DNS record at your domain provider, e.g. status.example.org with A (and ideally AAAA) pointing to your server.
  2. Sign in to the server via SSH and start the installation:
  3. Enter the domain. The script downloads the current version to /opt/stacktra-monitor, checks its checksum, creates random keys, starts everything, sets up the nightly backup and finally shows the setup code.
  4. Open https://status.example.org/setup, enter the code and follow the wizard: name, account, second factor (app, e-mail or Discord) and first monitors.
curl -fsSL https://stacktra.de/install.sh | sudo bash

Without questions, e.g. from a script: curl -fsSL https://stacktra.de/install.sh | sudo DOMAIN=status.example.org bash

Lost the setup code? cd /opt/stacktra-monitor && sudo docker compose logs panel | grep "setup code"

By hand

https://stacktra.de/download/latest.json names the file and SHA-256 of the current version. Download it, check it with sha256sum -c, unpack it and run sudo deploy/install.sh in the unpacked folder.

Monitors

Under Admin → “Add monitor”: choose a type, enter the target, set the interval and retries. “Run test” checks right away, before you save.

  • Public or private: public monitors show on the status page, private ones only when signed in.
  • Groups and order are arranged by drag and drop.
  • “Depends on” connects devices: if the switch fails, you get one alert instead of one per device behind it. The topology (Admin → Topology) shows the tree.
  • Reverse mode: “reachable = problem”, e.g. for a port that should never be open.
  • Push monitors: a service reports in itself, e.g. a backup script with curl at its end. If the report doesn’t come, it counts as down. The address is in the editor.

Agent for the homelab

The agent checks everything the panel can’t reach directly, for example devices in your home network. It runs as a small Docker container on a machine in your homelab and only connects outwards to the panel – no port has to be open at home.

  1. In the panel: Settings → Check locations → “Add agent”, name e.g. “Homelab”.
  2. The panel shows a command with a one-time code (valid for 30 minutes). Run it on the machine in your homelab:
  3. From now on choose the location “Homelab” under “Checked by” in the monitor editor.
curl -fsSL https://status.example.org/agent/install.sh | sudo bash -s -- ONE-TIME-CODE

Updating the agent: run the same command again without a code. The agent only runs SSH monitors if you allow it: add --ssh.

Notifications

Discord via webhook

In Discord: channel settings → Integrations → Webhooks → “New webhook” → copy URL. In the panel under Settings → Notifications add a Discord channel with this URL.

E-mail

Under Settings → Email enter your SMTP server and send a test mail. Then add an email channel under Notifications.

Discord bot (optional)

  1. On discord.com/developers create a new application. Under “Bot”: “Reset Token”, copy the token and switch off “Public Bot”.
  2. Under OAuth2 → URL Generator: scopes “bot” and “applications.commands”, permissions “Send Messages”, “Embed Links”, “Read Message History”. Open the URL and choose your server.
  3. In the panel under Settings → Discord bot enter the token, choose the alert channel (or /setup channel in Discord) and the role that may use buttons and commands.

Alert rules under Settings → Notifications: escalation levels, quiet hours, reminders, grouping and flapping protection.

Status page, incidents, maintenance

The status page on your domain only shows public monitors. Signed in, /monitoring shows all of them with details.

  • Incidents are created automatically on outages. You post updates in the panel or with a button in Discord; visitors see them on the status page.
  • Maintenance (Admin → Maintenance) suppresses alerts and doesn’t count against uptime. “What if?” in the topology plans maintenance for a device and everything behind it.
  • Status subscriptions: visitors subscribe to outages by e-mail (Settings → Notifications → Status subscriptions).
  • Badges and a widget for other websites are under Settings → Embed.
  • Imprint and privacy policy: Settings → Imprint & privacy.

API

Under Settings → API you create keys: “Read only” or “Read + write”. A key may never do more than the person who created it. All commands and examples are there in the panel.

curl -H "Authorization: Bearer stk_…" https://status.example.org/api/v1/summary

Maintenance from a script, e.g. during an update:

curl -X POST -H "Authorization: Bearer stk_…" -H "Content-Type: application/json" \
  -d '{"title": "Proxmox update", "groupIds": ["3"], "minutes": 30}' \
  https://status.example.org/api/v1/maintenances

Updates and backups

The panel shows new versions under Settings → System and sends you a message. An update:

sudo /opt/stacktra-monitor/deploy/deploy.sh

This gets the new version, checks it, takes a backup, rebuilds, starts and checks that everything runs. The previous version stays in /opt/stacktra-monitor.old until the next update.

Backups: every night at 03:15 to /var/backups/stacktra (the last 14). In the panel under Settings → Backup there are also encrypted backups to download and restore.

Keep a copy of /opt/stacktra-monitor/deploy/.env somewhere else. Without the SECRET_KEY in it, passwords stored in monitors can’t be read any more.

Server protection (Ubuntu)

Optional for Ubuntu servers: block lists of known attackers (Spamhaus, blocklist.de and more, refreshed every 4 hours), limits against floods, a port scan trap, fail2ban for SSH and web, key-only SSH and a Discord message when the server needs you (e.g. a reboot after updates).

sudo bash /opt/stacktra-monitor/deploy/guard/install.sh

Add an SSH key for root first – afterwards SSH only works with it. Without your confirmation the script rolls everything back after 5 minutes. If you open more ports later, add them to /etc/stacktra-guard/ports.nft as well.

Troubleshooting

  • Is everything running? cd /opt/stacktra-monitor && sudo docker compose ps
  • What does the panel say? sudo docker compose logs -f panel
  • No HTTPS certificate: does the domain point to the server (dig +short status.example.org)? Are ports 80 and 443 open?
  • In the panel under Settings → System: state of database, disk, clock, certificate and agents.