Import documentation: README.md
Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
This commit is contained in:
arsam
@@ -0,0 +1,157 @@
|
|||||||
|
# Dash — uptime observatory
|
||||||
|
|
||||||
|
A self-hosted uptime monitoring dashboard in a single binary. A Go check
|
||||||
|
engine with SQLite persistence streams live status over SSE into a
|
||||||
|
hand-built React frontend: three bespoke SVG circular visualizations with
|
||||||
|
spring physics, full RTL (Farsi) support, and a shareable public status mode.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## What it does
|
||||||
|
|
||||||
|
- **Five check types** — HTTP (status + latency), TCP port, TLS certificate
|
||||||
|
expiry (days remaining), ICMP ping, and Docker (container running +
|
||||||
|
healthcheck status via the daemon socket). Each target runs on its own
|
||||||
|
interval.
|
||||||
|
- **Flap detection** — N consecutive failures before a target is marked
|
||||||
|
down, M consecutive successes before it recovers. No alert noise from a
|
||||||
|
single dropped packet.
|
||||||
|
- **Incident grouping** — one incident spans the entire down period, from
|
||||||
|
the first failed check of the streak until recovery.
|
||||||
|
- **Live stream** — `/api/stream` pushes every probe and every confirmed
|
||||||
|
state transition over Server-Sent Events. The UI never polls.
|
||||||
|
- **Every result persisted** — timestamp, latency, status, error string in
|
||||||
|
SQLite (pure Go driver, no CGO), pruned after `history_days`.
|
||||||
|
|
||||||
|
## The frontend
|
||||||
|
|
||||||
|
Three circular instruments, all hand-built SVG + Framer Motion (no charting
|
||||||
|
libraries):
|
||||||
|
|
||||||
|
1. **Status rings** — one per target. The outer arc fills to the uptime
|
||||||
|
percentage over the selected window (24H/7D) and springs to every new
|
||||||
|
value; the inner brass gauge encodes latency on a log scale (1ms–2.5s);
|
||||||
|
each completed probe lands as a visible pulse; confirmed state changes
|
||||||
|
ripple outward. Click a ring and it travels into a detail view (shared
|
||||||
|
layout transition) with a latency sparkline, a per-target day dial, and
|
||||||
|
recent incidents.
|
||||||
|
2. **Orbital overview** — every target orbits the system core at
|
||||||
|
Kepler-flavored speeds (inner orbits run faster). Healthy bodies drift
|
||||||
|
calmly with motion trails, degraded ones breathe, a down body breaks its
|
||||||
|
orbit outward and flares red over the scar of its old path. The core
|
||||||
|
carries fleet-wide uptime and a brass scanner hand.
|
||||||
|
3. **Day dial** — a 24-hour clock face. Each of the last 24 hours is one
|
||||||
|
segment at its true wall-clock position, colored by status. Hours
|
||||||
|
without data stay hairline-thin. A brass hand marks now. One glance, one
|
||||||
|
full day.
|
||||||
|
|
||||||
|
Plus: a boot sequence where the instruments draw themselves in, staggered;
|
||||||
|
`prefers-reduced-motion` collapses all motion to fully-formed static
|
||||||
|
rendering; **فارسی / RTL** is a first-class layout mode (mirrored layout,
|
||||||
|
Vazirmatn type, Persian digits and the Persian solar calendar via `fa-IR`);
|
||||||
|
**dark and light themes** (persisted, both tuned variants of the same brass
|
||||||
|
/ ink design language); and a **Status** mode — the same instruments
|
||||||
|
stripped to a clean, shareable public status page.
|
||||||
|
|
||||||
|
Continuous motion (the orbital field, the scanner hand) runs outside React
|
||||||
|
entirely — one animation-frame loop mutates SVG attributes directly, so the
|
||||||
|
page stays at full frame rate regardless of target count. No SVG filters,
|
||||||
|
no blend modes on hot layers.
|
||||||
|
|
||||||
|
## Build
|
||||||
|
|
||||||
|
Requires Go ≥ 1.22 and Node ≥ 20. The frontend must be built first because
|
||||||
|
the binary embeds it via `go:embed`.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# 1. build the frontend into web/dist
|
||||||
|
cd web && npm install && npm run build && cd ..
|
||||||
|
|
||||||
|
# 2. compile the single binary (web/dist is embedded)
|
||||||
|
go build -o dash .
|
||||||
|
```
|
||||||
|
|
||||||
|
The result is one self-contained file, `dash`. Copy it and a `targets.yaml`
|
||||||
|
to any Linux/macOS/Windows box — nothing else to install.
|
||||||
|
|
||||||
|
## Run
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./dash # uses ./targets.yaml, ./dash.db, :8080
|
||||||
|
./dash -config /etc/dash/targets.yaml -db /var/lib/dash.db -listen :9090
|
||||||
|
```
|
||||||
|
|
||||||
|
Open http://localhost:8080.
|
||||||
|
|
||||||
|
> **ICMP checks** need raw-socket privileges. Run as root, or grant the
|
||||||
|
> binary `CAP_NET_RAW` (`setcap cap_net_raw+ep ./dash`), or allow
|
||||||
|
> unprivileged ping (`sysctl net.ipv4.ping_group_range="0 2147483647"`).
|
||||||
|
> Other check types work without any privileges.
|
||||||
|
|
||||||
|
## Configuration — targets.yaml
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
settings:
|
||||||
|
listen: ":8080" # bind address
|
||||||
|
db: "dash.db" # sqlite file
|
||||||
|
history_days: 30 # raw check retention
|
||||||
|
|
||||||
|
targets:
|
||||||
|
- id: example-web # unique slug (required)
|
||||||
|
name: "Example Website"
|
||||||
|
type: http # http | tcp | tls | icmp
|
||||||
|
url: https://example.com # http → url, tcp/tls → address, icmp → host
|
||||||
|
interval: 15s # time between checks (default 30s)
|
||||||
|
timeout: 5s # per-check timeout (default 5s)
|
||||||
|
fail_threshold: 3 # consecutive fails → down (default 3)
|
||||||
|
recover_threshold: 2 # consecutive oks → up (default 2)
|
||||||
|
expect_status: 200 # http only: require exact status
|
||||||
|
degraded_latency_ms: 1500 # mark degraded above this latency
|
||||||
|
|
||||||
|
- id: github-tls
|
||||||
|
name: "GitHub TLS"
|
||||||
|
type: tls
|
||||||
|
address: github.com:443
|
||||||
|
interval: 5m
|
||||||
|
warn_days: 21 # tls only: degraded when cert expires sooner
|
||||||
|
|
||||||
|
- id: my-container
|
||||||
|
name: "My Container"
|
||||||
|
type: docker
|
||||||
|
container: my-container # docker container name
|
||||||
|
interval: 30s
|
||||||
|
# socket: /var/run/docker.sock (default)
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Docker checks** read the daemon socket. Run the binary as a user in the
|
||||||
|
> `docker` group (or `SupplementaryGroups=docker` in the systemd unit). A
|
||||||
|
> container is *up* when running, *degraded* while its healthcheck reports
|
||||||
|
> `starting`, and failing when stopped or `unhealthy`.
|
||||||
|
|
||||||
|
## API
|
||||||
|
|
||||||
|
| Endpoint | Description |
|
||||||
|
| --- | --- |
|
||||||
|
| `GET /api/targets` | Current state of all targets: flap-filtered status, last check, 24h/7d uptime, latency percentiles, open incident |
|
||||||
|
| `GET /api/targets/{id}/history?range=24h` | Time series: downsampled points plus 24 aggregate buckets (`range`: `30m`, `24h`, `7d`, …) |
|
||||||
|
| `GET /api/incidents?range=7d` | Grouped incidents, ongoing first |
|
||||||
|
| `GET /api/stream` | SSE: `snapshot` on connect, then `check` per probe and `state` per confirmed transition |
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
```sh
|
||||||
|
go run . & # backend on :8080
|
||||||
|
cd web && npm run dev # vite on :5173, proxies /api → :8080
|
||||||
|
```
|
||||||
|
|
||||||
|
## Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
main.go, webfs.go entrypoint + embedded frontend
|
||||||
|
internal/config targets.yaml parsing, defaults, validation
|
||||||
|
internal/checker the four probe implementations
|
||||||
|
internal/engine scheduler, flap detection, incidents, SSE hub
|
||||||
|
internal/store sqlite persistence (modernc.org/sqlite, no CGO)
|
||||||
|
internal/api REST + SSE handlers
|
||||||
|
web/ React + TypeScript + Vite + Tailwind v4 + Motion
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user