Ghayamah-Uptime/README.md

# Uptime Kuma POC — Monitoring & Alerting on Ghaymah Cloud

## Goal

Deploy Uptime Kuma as a containerized app on Ghaymah Cloud, prove out
HTTP monitoring + Telegram alerting, and expose a public status page —
without building a monitoring system from scratch.

## Architecture

```mermaid
flowchart TD
    Internet((🌍 Internet))

    subgraph GhaymahCloud ["☁️ Ghaymah Cloud"]
        UK["🚀 Uptime Kuma<br/>(Port: 3001)"]
        DemoWeb["🌐 demo-web-server<br/>(NGINX :80)"]
    end

    Internet --> UK
    Internet --> DemoWeb
    
    UK -- "HTTP Check<br/>(Every 60s)" --> DemoWeb
    UK -. "Alert on Down/Up" .-> Telegram{"📱 Telegram Channel"}
    UK -. "Exposes" .-> PublicPage(["📊 Public Status Page"])
    
    style Internet fill:#f9f9f9,stroke:#333,stroke-width:2px;
    style Telegram fill:#2CA5E0,stroke:#fff,stroke-width:2px,color:#fff;
    style PublicPage fill:#4CAF50,stroke:#fff,stroke-width:2px,color:#fff;
    classDef cloud fill:#f0f8ff,stroke:#4a90e2,stroke-width:2px,stroke-dasharray: 5 5;
    classDef container fill:#ffffff,stroke:#333333,stroke-width:1px,shadow:true;
    class GhaymahCloud cloud;
    class UK,DemoWeb container;
```

## What was deployed

| App               | Image                     | Port | Instances | Volume       |
|--------------------|----------------------------|------|-----------|--------------|
| `uptime-kuma`      | `louislam/uptime-kuma:2`  | 3001 | 1         | `/app/data`  |
| `demo-web-server`  | `nginx`                   | 80   | 1         | none         |
| `status-page`      | `nginx:alpine`            | 8080 | 1         | none         |

Uptime Kuma is intentionally kept at **1 instance** — it stores its data
in a local SQLite database, so scaling it out would split monitor history
across separate, inconsistent instances.

`demo-web-server` (plain nginx) was added as a self-owned target to
monitor, so the POC watches infrastructure we actually control rather
than a third-party test endpoint.

`status-page` is a custom GitHub-style status page (HTML/CSS/JS) served
by nginx. It fetches live data from the Uptime Kuma public API and
displays service health with heartbeat bars and uptime percentages.

## Monitoring setup

| Monitor | Type | Target | Interval |
|---------|------|--------|----------|
| `test app` | HTTP(s) | `https://demo-web-server-web-9b9b121d.hosted.cumin.dev/` | 60s |
| `test uptime kuma` | HTTP(s) | `https://uptime-kuma-web-3aa83c30.hosted.cumin.dev/` | 60s |

Both monitors use 0 retries (flags Down immediately) and a 48-second
timeout. `test uptime kuma` is a self-monitoring check — Uptime Kuma
watching itself to detect if the monitoring service goes down.

During setup the `test app` monitor was pointed first at `httpstat.us/200`
(unstable, frequent 502s) and then `httpbin.org/status/200` for stability
testing, before finally being switched to the self-owned nginx instance.

## Alerting

- **Channel:** Telegram
- Created via `@BotFather`, bot token and chat ID configured as an
  Uptime Kuma notification, linked to the `test app` monitor.
- **Tested:** forced a Down state (pointed the monitor at an endpoint
  returning HTTP 502) and confirmed a Telegram alert arrived; then
  restored a healthy endpoint and confirmed the recovery (Up) alert
  arrived as well.

## Public Status Page

### Built-in (Uptime Kuma)
- **URL:** https://uptime-kuma-web-3aa83c30.hosted.cumin.dev/status/ghaymah-status
- **Access:** public, no login required
- Shows overall status, both monitors grouped under **Services**, uptime
  percentages, and heartbeat history bars.

### Custom (GitHub-style)
- **Files:** `status-page/index.html` + `status-page/nginx.conf`
- **Local:** `http://localhost:8080` (via `docker compose up status-page`)
- Fetches live data from the Uptime Kuma public API; proxies it through
  nginx to avoid CORS. Displays 90-heartbeat bars, 24h/30d uptime %,
  and animated status indicators. Auto-refreshes every 60 seconds.

## Data persistence

Uptime Kuma stores its SQLite database and configuration under
`/app/data` inside the container, which is mounted to a persistent
Ghaymah volume. Restarting or redeploying the container does not lose
monitors, notification settings, or status page configuration.

## Export / configuration snapshot

This Uptime Kuma version (2.5.4) does not currently expose a
Settings > Backup/Export screen, so `uptime-kuma-config-export.json`
in this folder was assembled by hand from the live dashboard to
document every setting used in this POC (monitor config, notification
setup, status page config, deployment parameters). Secrets (bot
token, chat ID) are intentionally redacted from that file.

## How to verify it yourself

1. Open the [status page](https://uptime-kuma-web-3aa83c30.hosted.cumin.dev/status/ghaymah-status) — no login needed.
2. To test alerting: edit the `test app` monitor's URL to point at any
   endpoint that returns a non-2xx status, save, and wait up to 60
   seconds for the next heartbeat. A Down alert should arrive on
   Telegram. Point it back at a healthy URL to see the Up recovery
   alert.

## Security & Data Resilience

- **Independent Health Tracking:** The Uptime Kuma stack functions as an independent observer. The persistence layer retains the complete outage and metrics history inside an isolated volume.
- **Failover Alerts Validation:** Explicitly validated notification webhooks logic to verify immediate alerting upon HTTP failures and automatic recovery resolution (Up events).
- **Persistent Storage Configuration:** Critical settings (like SQLite DB, configurations) are safely coupled to `/app/data` volume mount to circumvent ephemeral container cycles.

## Next steps (not yet done)

- Deploy the custom status page to Ghaymah Cloud via `gy deploy` to
  give it a public URL.
- Add monitors for real application services once a backend app is
  deployed, replacing the current demo targets.