path: root/README.md

<p align="center">
  <img src="frontend/static/favicon.svg" width="80" alt="YAUM logo" />
</p>

<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.
```