Installation and Setup

Installation & Setup

Running it with native Python (recommended)

You need Python 3.10+ on the machine that will host this.

cd status-portal
pip install -r requirements.txt
cp .env.example .env   # optional, or just export the env vars yourself
python app.py

Open http://localhost:5000 → public page.

Open http://localhost:5000/admin → asks you to create the admin password on first launch (no default password, you choose it). Write it down — there's no "forgot password" flow.

Once you've confirmed it works, Ctrl+C to stop — app.py is the dev server, not meant to run 24/7. For continuous/production use, run python serve_waitress.py instead — it's a real WSGI server (waitress), not Flask's dev server.

Use whatever your OS provides for running a background process on boot (a systemd unit, Task Scheduler, a process manager like pm2/supervisord, etc.) to run python serve_waitress.py on startup, from the status-portal folder.

The session key

The admin session cookie is signed with a secret key. You don't have to set one: on first start the app generates a key and saves it to instance/secret_key (readable only by the account running the portal), and reuses it from then on — so restarts, updates and reboots leave you signed in.

Set PORTAL_SECRET_KEY (in .env or as a real env var) if you'd rather keep the key somewhere you control. Setting it always wins over the generated file.

Before 1.6.1 this key was random per process whenever PORTAL_SECRET_KEY was unset, which is why restarts used to log you out at seemingly random moments.

How long you stay signed in

Sessions last for 12 hours of inactivity by default, on every device the same way. Any page you load resets the clock. Change it (or switch it off) under Settings → Admin session timeout; with the timeout off, a sign-in still expires after 30 days.

Publishing it

This app only needs to publish its own port — how you expose that from there is entirely up to you: a Tailscale/VPN network, a reverse proxy (Caddy, nginx, Traefik...) in front of a real domain, a tunnel (Cloudflare Tunnel, etc.), or nothing at all if it's LAN-only. None of that is this project's concern — point whatever you use at http://<this-machine>:<PORTAL_PORT> and you're done.

See Security Notes before exposing this beyond a LAN/VPN.

Running it with Docker (optional alternative)

If you'd rather run it in a container instead of directly on the host:

cp .env.example .env
# every setting in .env is optional - edit whatever you want to change
docker compose up -d

Open http://localhost:5000 (or whatever HOST_PORT you set in .env). The SQLite database lives in a named Docker volume (portal_data), so it survives rebuilds/updates.

All configuration lives in .env — see the Configuration Reference for every available option (ports, health-check frequency, public refresh frequency). No code to edit, ever, for day-to-day tuning.