diff options
| author | zwlucas <lucas.fariamo08@gmail.com> | 2026-05-29 21:55:09 +0000 |
|---|---|---|
| committer | zwlucas <lucas.fariamo08@gmail.com> | 2026-05-29 21:55:09 +0000 |
| commit | e9235043e92783f58eeb174109a9e5964a4f35f8 (patch) | |
| tree | 373673ba2d4d3b5f3cdee353ace342ae684cddd8 /README | |
| parent | f0206d0c9ad7e082b43b71b085beecbcb7e3dc63 (diff) | |
| download | yaum-master.tar.gz yaum-master.zip | |
Signed-off-by: zwlucas <lucas.fariamo08@gmail.com>
Diffstat (limited to 'README')
| -rw-r--r-- | README | 237 |
1 files changed, 0 insertions, 237 deletions
@@ -1,237 +0,0 @@ - -<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. -``` |