status

Status Page

Small Gin-based status page that monitors a list of services from config.yaml, exposes a JSON API, and pushes live updates over WebSockets.

Run

go run .

The app serves the UI at http://127.0.0.1:8080 by default.

Environment Variables

The server reads these environment variables at startup:

ADDR : Full listen address for Gin, such as 127.0.0.1:8080, 0.0.0.0:8080, or :8080.

PORT : Port-only fallback. If ADDR is not set and PORT=9090, the server listens on :9090.

CONFIG_PATH : Path to the monitor config file. Defaults to config.yaml.

THEME : UI theme to render. Supported values: dark or light. Default: dark.

TLS_CERT_FILE : Optional path to a PEM-encoded server certificate. When set with TLS_KEY_FILE, the app listens over HTTPS.

TLS_KEY_FILE : Optional path to the PEM-encoded private key that matches TLS_CERT_FILE.

Address Precedence

The listen address is chosen in this order:

1. ADDR
2. PORT
3. Default 127.0.0.1:8080

HTTPS behavior:

1. If both TLS_CERT_FILE and TLS_KEY_FILE are set, Gin starts with TLS.
2. If neither is set, the app serves plain HTTP.
3. If only one is set, startup fails fast.

Examples:

ADDR=0.0.0.0:8080 go run .

PORT=9090 go run .

CONFIG_PATH=/etc/status/config.yaml go run .

THEME=light go run .

ADDR=:8443 TLS_CERT_FILE=server.crt TLS_KEY_FILE=server.key go run .

Config File

The app expects a YAML file with a top-level monitors list.

Each monitor must include:

• name: Friendly label shown in the UI
• url: Target to check, including scheme
• category: Group label shown on the tile

Example:

monitors:
  - name: GitHub
    url: https://github.com
    category: Developer Tools

  - name: Cloudflare DNS
    url: dns://cloudflare.com
    category: DNS

  - name: Google TLS
    url: tls://www.google.com:443
    category: TLS

  - name: OpenAI Reachability
    url: ping://platform.openai.com:443
    category: Network

Supported URL Schemes

http:// and https://

Performs an HTTP GET and marks the monitor healthy for 2xx and 3xx responses.

Example:

- name: Example API
  url: https://httpbin.org/status/200
  category: API

dns://

Resolves host records with DNS lookup.

Example:

- name: Cloudflare DNS
  url: dns://cloudflare.com
  category: DNS

Notes:

• Use a hostname only.
• The UI will show the resolved addresses in the details area.

tls://

Opens a TLS connection and inspects the presented certificate.

Example:

- name: Google TLS
  url: tls://www.google.com:443
  category: TLS

What it reports:

• Whether the certificate chain verifies as signed/trusted
• Whether hostname validation passes
• Whether the certificate is currently time-valid
• The certificate expiration date

Notes:

• Include a port when possible. If omitted, the app uses 443.
• A TLS monitor is only marked healthy when trust, hostname validation, and certificate dates all pass.

ping://

Performs a TCP reachability check by opening a TCP connection to the target.

Example:

- name: Google Ping
  url: ping://8.8.8.8
  category: Network

You can also specify a port:

- name: OpenAI Reachability
  url: ping://platform.openai.com:443
  category: Network

Notes:

• This is a TCP connect check, not ICMP echo.
• If no port is supplied, the app uses 443.

Validation Rules

At startup, the server fails fast when:

• config.yaml cannot be read
• the YAML is invalid
• monitors is empty
• a monitor is missing name, url, or category

API Endpoints

GET / : Status page UI

GET /api/status : Current status snapshot as JSON

GET /ws : WebSocket endpoint for live service_update messages

Docker

Build the image locally:

docker build -t bmallenxs/status:latest .

Run it with the bundled config:

docker run --rm -p 8080:8080 bmallenxs/status:latest

Run it with your own config:

docker run --rm \
  -p 8080:8080 \
  -v "$(pwd)/config.yaml:/app/config.yaml:ro" \
  bmallenxs/status:latest

Run it with HTTPS enabled:

docker run --rm \
  -p 8443:8443 \
  -e ADDR=:8443 \
  -e TLS_CERT_FILE=/certs/server.crt \
  -e TLS_KEY_FILE=/certs/server.key \
  -v "$(pwd)/config.yaml:/app/config.yaml:ro" \
  -v "$(pwd)/certs:/certs:ro" \
  bmallenxs/status:latest

The container defaults to:

• ADDR=:8080
• CONFIG_PATH=/app/config.yaml

Publish Script

publish.sh builds and pushes the image as bmallenxs/status:latest.

Usage:

./publish.sh