From e9235043e92783f58eeb174109a9e5964a4f35f8 Mon Sep 17 00:00:00 2001 From: zwlucas Date: Fri, 29 May 2026 18:55:09 -0300 Subject: fix?: readme Signed-off-by: zwlucas --- README.md | 237 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..2bf2c47 --- /dev/null +++ b/README.md @@ -0,0 +1,237 @@ + +

YAUM β€” Yet Another Uptime Monitor

+ +

+ A private, ultra-performant, and minimalist uptime monitoring dashboard + for websites and HTTP services, built with Go and SvelteKit. +

+ +

+ Go 1.25 + Svelte 5 + SvelteKit 2 + TailwindCSS 3 + Docker ready + MIT License +

+ +--- + +## πŸš€ Key Features + +- **⏱️ High-concurrency monitoring engine** β€” Go goroutines fire per-service HTTP checks at configurable intervals (down to 10 seconds granularity). +- **πŸ“Š Real-time public dashboard** β€” Server-Sent Events (SSE) push heartbeats and status transitions to the browser as they happen. +- **πŸ” Password-protected admin panel** β€” Single-admin JWT auth with bcrypt master password; manage services, maintenances, and server metrics. +- **πŸ“ˆ Response-time charts** β€” SVG-based latency visualization with colored segments, gradient fill, and dynamic y‑axis scaling. +- **πŸ”” Discord webhook alerts** β€” Instant notifications on status transitions. +- **πŸ“‹ Keyword checking** β€” Validate response bodies for expected content. +- **πŸ“¦ Service groups** β€” Organize services into named groups for cleaner dashboards. +- **πŸ› οΈ Maintenance windows** β€” Schedule maintenance periods that display a global banner. +- **πŸ“œ Activity log** β€” Real-time log of checks, transitions, creations, and deletions. +- **πŸ“„ SVG status badges** β€” Lightweight embeddable badges for READMEs or external pages. +- **πŸ“Ί Kiosk / TV mode** β€” Full-screen dashboard for wall-mounted monitors with Screen Wake Lock API integration (prevents sleep). +- **πŸ”’ SSL/TLS inspection** β€” Automatic extraction of certificate issuer, expiry date, and days remaining; yellow alert when < 7 days. +- **πŸ–₯️ Host server health metrics** β€” CPU, RAM, and Disk usage displayed directly in the admin panel (via `gopsutil`). +- **🐳 Single-binary deployment** β€” Entire frontend embedded into the Go binary via `go:embed`; deploy with a single executable or Docker. +- **↔️ History pagination** β€” Paginated check history (50 per page) with SSE updates on page 1. + +--- + +## πŸ› οΈ Tech Stack + +| Component | Technology | +| ----------------------- | ------------------------------------------------------- | +| **Backend Language** | Go 1.25 (`net/http`, `pgx/v5`, `golang-jwt`, `bcrypt`) | +| **Frontend Framework** | SvelteKit 2 + Svelte 5 | +| **Database** | PostgreSQL (pgx/v5) β€” in-memory fallback for dev | +| **Styling** | TailwindCSS 3 + custom dark theme | +| **Real-time transport** | Server-Sent Events (SSE) | +| **Server metrics** | `shirou/gopsutil/v4` (CPU / RAM / Disk) | +| **Deploy / Infra** | Docker multistage (`alpine:3.20`), single binary | +| **Authentication** | JWT (7 days) + bcrypt master password | + +--- + +## πŸ—‚οΈ Project Architecture + +``` +yaum/ +β”œβ”€β”€ backend/ # Go monolith (API + Worker + SSE) +β”‚ β”œβ”€β”€ cmd/server/main.go # Entry point +β”‚ β”œβ”€β”€ internal/ +β”‚ β”‚ β”œβ”€β”€ api/ # HTTP handlers & router +β”‚ β”‚ β”‚ β”œβ”€β”€ handler.go # All route handlers +β”‚ β”‚ β”‚ β”œβ”€β”€ router.go # ServeMux + SPA file server +β”‚ β”‚ β”‚ β”œβ”€β”€ auth.go # JWT login, verify, middleware +β”‚ β”‚ β”‚ └── stream.go # SSE broadcaster endpoint +β”‚ β”‚ β”œβ”€β”€ monitor/ # Background checker +β”‚ β”‚ β”‚ β”œβ”€β”€ worker.go # Scheduling engine (10s tick granularity) +β”‚ β”‚ β”‚ └── checker.go # HTTP check + TLS inspection +β”‚ β”‚ β”œβ”€β”€ store/ # Data layer +β”‚ β”‚ β”‚ β”œβ”€β”€ store.go # Interface +β”‚ β”‚ β”‚ β”œβ”€β”€ memory.go # In-memory implementation +β”‚ β”‚ β”‚ └── postgres.go # PostgreSQL implementation +β”‚ β”‚ β”œβ”€β”€ model/types.go # Shared domain types +β”‚ β”‚ β”œβ”€β”€ config/config.go # Config loader (JSON + .env) +β”‚ β”‚ β”œβ”€β”€ alerts/ # Discord + Email notification +β”‚ β”‚ β”œβ”€β”€ sse/ # SSE broadcaster +β”‚ β”‚ β”œβ”€β”€ servermetrics/ # CPU / RAM / Disk collector +β”‚ β”‚ └── static/ # Embeds the frontend build +β”‚ β”œβ”€β”€ migrations/ # PostgreSQL schema files +β”‚ β”œβ”€β”€ config.json # Server configuration +β”‚ └── .env.example # Environment template +β”‚ +β”œβ”€β”€ frontend/ # SvelteKit SPA +β”‚ β”œβ”€β”€ src/ +β”‚ β”‚ β”œβ”€β”€ routes/ +β”‚ β”‚ β”‚ β”œβ”€β”€ +page.svelte # Public dashboard +β”‚ β”‚ β”‚ β”œβ”€β”€ login/ # Login page +β”‚ β”‚ β”‚ β”œβ”€β”€ status/[id]/ # Public service detail +β”‚ β”‚ β”‚ └── (admin)/admin/ # Admin panel +β”‚ β”‚ └── lib/ +β”‚ β”‚ β”œβ”€β”€ components/ # ServiceCard, ActivityLog, modals +β”‚ β”‚ β”œβ”€β”€ realtime.ts # SSE client subscription +β”‚ β”‚ └── api.ts # API client helpers +β”‚ └── svelte.config.js # adapter-static (SPA fallback) +β”‚ +β”œβ”€β”€ scripts/ # Build helpers +β”‚ β”œβ”€β”€ build-prod.sh # Unix production build +β”‚ └── build-prod.ps1 # Windows production build +β”‚ +β”œβ”€β”€ Dockerfile # Multistage docker build +└── README.md # This file +``` + +### How it works + +1. **Worker** β€” A background goroutine iterates active services every 10 seconds. For each service whose `interval_seconds` has elapsed since the last check, it fires a goroutine that performs an HTTP GET (with optional keyword validation and TLS certificate extraction). +2. **Persistence** β€” Each heartbeat is stored in PostgreSQL (or in-memory store for development) and the latest SSL info is saved per service. +3. **Real-time streaming** β€” Every heartbeat is broadcast to all connected browser clients via SSE at `/api/stream`. +4. **Router** β€” The Go `net/http` ServeMux (Go 1.22+ pattern matching) handles API routes (`/api/*`) and falls through to an embedded static file server for the SvelteKit frontend. Any path that doesn't match a file gets the SPA fallback (`200.html`), enabling client-side routing for `/admin`, `/status/[id]`, and `/login`. + +--- + +## βš™οΈ Getting Started β€” Local Development + +### Prerequisites + +- [Go](https://go.dev/dl/) 1.25+ +- [Node.js](https://nodejs.org/) 20+ +- [PostgreSQL](https://www.postgresql.org/download/) 16+ (optional β€” the app falls back to an in-memory store) + +### 1. Clone and configure + +```bash +git clone https://git.devlucas.me/yaum.git +cd yaum/backend +cp .env.example .env +``` + +Edit `.env` with your credentials: + +```env +ADMIN_USERNAME=admin +ADMIN_PASSWORD=your-secure-password +JWT_SECRET=your-random-64-char-secret +``` + +Optionally set up PostgreSQL in `config.json` (the app works without it using an in-memory store with seed data). + +### 2. Start the Go backend + +```bash +cd backend +go run ./cmd/server/ +``` + +The API will be available at `http://localhost:8080`. + +### 3. Start the SvelteKit frontend (dev mode) + +```bash +cd frontend +npm install +npm run dev +``` + +The Vite dev server runs at `http://localhost:5173` and proxies `/api/*` requests to the Go backend. + +Open `http://localhost:5173` in your browser. Navigate to `/login` and sign in with your admin credentials. + +--- + +## 🐳 Production & Deployment + +YAUM uses a **multistage Docker build** that produces a ~20 MB image containing everything needed to run. + +### Build the image + +```bash +docker build -t yaum . +``` + +### Run the container + +Mount your `config.json` and `.env` file, and expose port 8080: + +```bash +docker run -d \ + --name yaum \ + -p 8080:8080 \ + -v /host/path/config.json:/app/config.json \ + -v /host/path/.env:/app/.env \ + yaum +``` + +### Build the binary manually + +To produce the single binary without Docker: + +```bash +# 1. Build the frontend +cd frontend && npm ci && npm run build + +# 2. Copy the static export into the Go embed directory +cp -r frontend/build backend/internal/static/build/ + +# 3. Compile the Go binary +cd backend +CGO_ENABLED=0 go build -ldflags="-s -w" -o yaum ./cmd/server/ +``` + +Run the resulting `backend/yaum` binary β€” it serves both the API and the frontend on the configured port (default `:8080`). + +### Platform-specific instructions + +| Platform | Script | +| ---------- | ------------------------ | +| Linux/macOS | `scripts/build-prod.sh` | +| Windows | `scripts\build-prod.ps1` | + +--- + +## πŸ“„ License + +``` +MIT License + +Copyright (c) 2026 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` -- cgit v1.2.3