diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..2bf2c47 --- /dev/null +++ b/README.md @@ -0,0 +1,237 @@ + +<h1 align="center">YAUM β Yet Another Uptime Monitor</h1> + +<p align="center"> + A private, ultra-performant, and minimalist uptime monitoring dashboard + for websites and HTTP services, built with <strong>Go</strong> and <strong>SvelteKit</strong>. +</p> + +<p align="center"> + <a href="#"><img src="https://img.shields.io/badge/Go-1.25-00ADD8?logo=go" alt="Go 1.25" /></a> + <a href="#"><img src="https://img.shields.io/badge/Svelte-5-FF3E00?logo=svelte" alt="Svelte 5" /></a> + <a href="#"><img src="https://img.shields.io/badge/SvelteKit-2-FF3E00?logo=svelte" alt="SvelteKit 2" /></a> + <a href="#"><img src="https://img.shields.io/badge/TailwindCSS-3-06B6D4?logo=tailwindcss" alt="TailwindCSS 3" /></a> + <a href="#"><img src="https://img.shields.io/badge/Docker-ready-2496ED?logo=docker" alt="Docker ready" /></a> + <a href="#"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" /></a> +</p> + +--- + +## π 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. +``` |