From b0d5268b150eb2298a03f303278e6c00c18b8509 Mon Sep 17 00:00:00 2001 From: Fede Date: Mon, 21 Sep 2026 18:33:26 -0300 Subject: [PATCH] Make the README a showcase landing page for Apollo. Add a branded SVG banner, badges, feature grid, architecture diagram, and clearer quick-start tables so the repo reads like a product, not a note dump. Co-authored-by: Cursor --- README.md | 207 +++++++++++++++++++++++++++++++---------- docs/apollo-banner.svg | 42 +++++++++ 2 files changed, 202 insertions(+), 47 deletions(-) create mode 100644 docs/apollo-banner.svg diff --git a/README.md b/README.md index 183764e..3430467 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,150 @@ -# Apollo - -Django + React API Health Monitor (monolith). +

+ Apollo — API Health Monitor +

+ +

+ Watch your APIs. Catch outages early. Ship with confidence. +

+ +

+ Quick start + Features + CI +

+ +

+ Django + Vite + Redux + Postgres + Docker + License +

+ +--- + +## Why Apollo? + +Most “health checks” stop at a green ping. +**Apollo** is a full monitoring cockpit: scheduled probes, transition alerts, incidents, a public status page, charts, and exports — in one Django + React monolith. + +```text + probe ──► assert ──► threshold ──► incident + │ │ + └──► webhook / email / Discord / Slack + └──► public /status page +``` -## Stack +--- -- **Backend:** Django 6 + DRF + httpx + Token auth + WhiteNoise + Gunicorn -- **Frontend:** React + Vite + Redux Toolkit + React Router (pnpm) -- **Data:** SQLite (local) or PostgreSQL (`DATABASE_URL`) -- **Ops:** Docker Compose (`db` + `web` + `worker`), GitHub Actions CI -- **Product:** multi-user ownership, advanced assertions, quiet hours, incident ack, charts, exports, Discord/Slack, status page, retention +## Features -## Quick start (local) + + + + + + + + + + + + + +
+

🔭 Probes that mean it

+

HTTP methods, custom headers, bearer/basic auth, request bodies, SSL expiry, latency caps, body / header / JSON-path assertions.

+ 		+

🚨 Alerts without noise

+

Transition-only notifications, failure thresholds, mute windows, quiet hours. Channels: webhook, email, Discord, Slack.

+
+

🩹 Incidents & ownership

+

Auto open/resolve, acknowledge in UI, multi-user ownership, optional registration, staff sees everything.

+ 		+

📣 Status the world can see

+

Public /status, branded title/subtitle/support link, tags, and live overall health.

+
+

📈 Ops dashboard

+

Uptime & latency charts, due checks, CSV export, paginated history, check retention.

+ 		+

🧱 Ship-ready stack

+

Poetry, pnpm, Docker Compose (db + web + worker), GitHub Actions CI, WhiteNoise + Gunicorn.

+
+ +--- + +## Quick start + +### Local (dev) ```bash cp .env.example .env -poetry install -poetry run python manage.py migrate -poetry run python manage.py seed +poetry install && poetry run python manage.py migrate && poetry run python manage.py seed pnpm --dir frontend install +# terminal 1 poetry run python manage.py runserver + +# terminal 2 pnpm --dir frontend dev ``` -- App: http://localhost:5173 — login **`apollo` / `apollo`** (or register if `APOLLO_ALLOW_REGISTER=true`) -- Public status: http://localhost:5173/status +| Surface | URL | +|--------|-----| +| **App** | http://localhost:5173 | +| **Public status** | http://localhost:5173/status | +| **Demo login** | `apollo` / `apollo` | -## Docker +### Docker (one shot) ```bash cp .env.example .env docker compose up --build ``` -- App: http://localhost:8000 -- Status: http://localhost:8000/status -- Worker runs due checks + `prune_checks` on an interval +| Surface | URL | +|--------|-----| +| **App + API** | http://localhost:8000 | +| **Status** | http://localhost:8000/status | -## Features +Worker runs due checks and prunes old results on an interval. + +--- -| Area | Details | -|------|---------| -| Auth | Login/logout/me + optional register; endpoints scoped by owner (staff sees all) | -| Endpoints | CRUD, tags, public, probe auth/headers/body, mute, quiet hours | -| Checks | Manual, due, history; body/header/JSON/latency/SSL assertions; failure threshold | -| Alerts | Webhook/email/Discord/Slack after N failures; muted by datetime or quiet hours | -| Incidents | Auto open/resolve; acknowledge via API/UI | -| Status page | Public `/status` + branding via `/api/status/config/` | -| Dashboard | Uptime, latency, charts, CSV export | -| Retention | Worker prunes checks older than `CHECK_RETENTION_DAYS` | +## Architecture -## Key API routes +```mermaid +flowchart LR + U[Operator UI] --> API[Django / DRF] + S[Public /status] --> API + API --> DB[(SQLite / Postgres)] + W[Check worker] --> API + W --> DB + API -->|alerts| C[Webhook · Email · Discord · Slack] +``` + +**Monolith layout:** React (Vite) talks to `/api/*`; production serves the built frontend via WhiteNoise. + +--- + +## API map | Method | Path | Auth | |--------|------|------| -| GET | `/api/health/` | public | -| GET | `/api/status/public/` | public | -| GET/PATCH | `/api/status/config/` | token | -| GET | `/api/exports/{checks\|alerts\|incidents}.csv` | token | -| POST | `/api/auth/login/` | public | -| POST | `/api/auth/register/` | public (if enabled) | -| GET | `/api/dashboard/` | token | -| CRUD | `/api/endpoints/` | token | -| GET | `/api/incidents/?status=open` | token | -| POST | `/api/incidents/{id}/acknowledge/` | token | -| GET/POST | `/api/tags/` | token | -| GET | `/api/alerts/` | token | - -## Env highlights - -See `.env.example` (`DATABASE_URL`, `CHECK_INTERVAL_SECONDS`, `CHECK_RETENTION_DAYS`, `APOLLO_ALLOW_REGISTER`, `EMAIL_*`, demo user, etc.). +| `GET` | `/api/health/` | public | +| `GET` | `/api/status/public/` | public | +| `GET/PATCH` | `/api/status/config/` | token | +| `POST` | `/api/auth/login/` · `/api/auth/register/` | public* | +| `GET` | `/api/dashboard/` | token | +| `CRUD` | `/api/endpoints/` | token | +| `GET` | `/api/incidents/?status=open` | token | +| `POST` | `/api/incidents/{id}/acknowledge/` | token | +| `GET` | `/api/exports/{checks\|alerts\|incidents}.csv` | token | + +\* Register only if `APOLLO_ALLOW_REGISTER=true`. + +--- ## Commands @@ -81,3 +156,41 @@ poetry run python manage.py prune_checks --dry-run pnpm --dir frontend build docker compose up --build ``` + +--- + +## Configuration + +Copy `.env.example` → `.env`. Highlights: + +| Variable | Purpose | +|----------|---------| +| `DJANGO_SECRET_KEY` | Required when `DJANGO_DEBUG=false` | +| `DATABASE_URL` | Postgres URL (empty → SQLite) | +| `CHECK_INTERVAL_SECONDS` | Worker loop | +| `CHECK_RETENTION_DAYS` | Auto-prune old checks | +| `APOLLO_ALLOW_REGISTER` | Open self-serve signup | +| `EMAIL_*` / mailer settings | Email alerts | + +--- + +## Project pulse + +```text + Apollo + ├── monitoring/ models · probes · alerts · incidents · status + ├── config/ Django settings & URLs + ├── frontend/ React + Redux + Vite UI + ├── docker/ entrypoint + worker + └── .github/ CI +``` + +--- + +

+ Built as a Django + React monolith · Designed to stay out of the way until something breaks +

+ +

+ Apollo mark +

diff --git a/docs/apollo-banner.svg b/docs/apollo-banner.svg new file mode 100644 index 0000000..738cb91 --- /dev/null +++ b/docs/apollo-banner.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Apollo + API Health Monitor + Uptime Incidents Alerts Public status + + + + Django + React + + Docker ready + + Postgres / SQLite + +