Uptime Guard

Portfolio-grade backend project for monitoring websites and APIs. The service stores projects and monitors, executes recurring health checks, opens and resolves incidents, and sends outbound webhook notifications when a monitor changes state.

Stack

• Python
• Django + Django REST Framework
• PostgreSQL
• Redis
• Celery
• SQLite for lightweight local mode
• Docker Compose for full infra mode

What This Project Shows

• Authenticated REST API for project and monitor management
• Public status page endpoint for portfolio demos
• Async monitor execution with Celery and Redis
• Incident lifecycle management with failure thresholds
• Outbound webhook notifications with HMAC signature support
• Fast local startup without Docker using SQLite and in-process Celery execution
• Dockerized full environment with web, worker, beat, Postgres, and Redis

Domain Model

• Project: tenant-style container owned by a user
• Monitor: HTTP endpoint check with interval, timeout, expected status codes, keyword, and latency threshold
• MonitorCheck: historical execution result for every run
• Incident: open/resolved outage record created after repeated failures
• NotificationEndpoint: webhook destination for incident events

API Surface

• POST /api/auth/token/ obtain auth token
• GET /api/dashboard/summary/ high-level metrics
• GET|POST /api/projects/
• GET|POST /api/monitors/
• POST /api/monitors/{id}/run/ queue an immediate check
• GET /api/checks/
• GET /api/incidents/
• GET|POST /api/notification-endpoints/
• GET / service overview with useful links
• GET /status/{project_slug}/ public status snapshot
• GET /health/ liveness check

Local Run Without Docker

1. Create a virtual environment: python -m venv .venv
2. Activate it in PowerShell: .\.venv\Scripts\Activate.ps1
3. Install dependencies: pip install -r requirements.txt
4. If .env does not exist, copy it from .env.example: Copy-Item .env.example .env
5. Run migrations: python manage.py migrate
6. Create demo data: python manage.py seed_demo
7. Start the API: python manage.py runserver

Local mode uses:

• SQLite instead of PostgreSQL
• in-memory cache instead of Redis
• CELERY_TASK_ALWAYS_EAGER=true, so POST /api/monitors/{id}/run/ executes immediately without a worker
• python manage.py run_due_checks for manual execution of scheduled checks during development

After startup:

• Root: http://127.0.0.1:8000/
• API: http://127.0.0.1:8000/api/
• Health: http://127.0.0.1:8000/health/
• Public status page: http://127.0.0.1:8000/status/portfolio-monitoring/

Use the token printed by seed_demo in:

Authorization: Token <token>

Docker Run

1. Copy .env.docker.example to .env.
2. Start the stack: docker compose up --build
3. Seed demo data inside the web container: docker compose exec web python manage.py seed_demo

This mode uses real PostgreSQL, Redis, Celery worker, and Celery beat.

Example Monitor Payload

{
  "project": 1,
  "name": "Main API",
  "monitor_type": "http",
  "method": "GET",
  "url": "https://api.example.com/health",
  "headers": {
    "Accept": "application/json"
  },
  "expected_status_codes": [200],
  "expected_keyword": "ok",
  "timeout_seconds": 10,
  "check_interval_seconds": 60,
  "failure_threshold": 3,
  "expected_response_time_ms": 1200,
  "is_active": true
}

Architecture Notes

• Celery beat runs monitoring.run_due_checks every minute.
• Due monitors are reserved before dispatch to reduce duplicate execution.
• perform_monitor_check stores the raw result, updates current monitor state, and opens or resolves incidents.
• Notification endpoints receive JSON payloads and an optional X-Uptime-Signature HMAC header.
• In non-Docker local mode, .env is loaded automatically by Django settings.
• In non-Docker local mode, immediate monitor runs work without a separate Celery process.

Tests

The repository includes basic API tests for token issuance and the public status endpoint. After installing dependencies, run:

python manage.py test