OrbitalWard

Beautiful, self-hosted infrastructure monitoring without the enterprise-tool headache.

OrbitalWard is an open-source monitoring appliance for homelabs, small businesses, and internal IT teams. The first target is a secure and attractive monitoring foundation with guided setup, website checks, alerts, notifications, and clean dashboards. It is not trying to be a full Zabbix or LibreNMS replacement in the first release.

Current Status

This repository contains the initial project foundation:

• FastAPI backend skeleton with authentication, roles, health checks, and core data models
• PostgreSQL and Alembic migration foundation
• Redis-backed worker service skeleton
• React, TypeScript, Vite, and Tailwind frontend shell
• Docker Compose development environment
• Initial product, architecture, security, discovery, alerting, plugin, and Gitea issue docs

The first working vertical slice is planned around website monitoring:

1. User logs in.
2. User adds a website monitor.
3. Worker checks HTTP status and expected text.
4. Results are stored.
5. Dashboard shows status.
6. Alert rules create incidents.
7. Mattermost, Zoom, or generic webhook notifications are sent.
8. Recovery notifications are sent when the website recovers.

Development Setup

Prerequisites:

• Docker and Docker Compose
• Node.js 20+ if running the frontend outside Docker
• Python 3.12+ if running backend or worker outside Docker

Copy the environment file:

cp .env.example .env

Start the development stack:

docker compose -f docker-compose.dev.yml up --build

Services:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API docs: http://localhost:8000/docs

Default local admin credentials come from .env:

• INITIAL_ADMIN_EMAIL=admin@example.com
• INITIAL_ADMIN_PASSWORD=change-me

Change these values before using OrbitalWard anywhere beyond local development.

Project Structure

backend/   FastAPI API, models, schemas, auth, migrations, and tests
frontend/  React/Vite app with the initial authenticated dashboard shell
worker/    Background scheduler and collector skeleton
docs/      Product, architecture, security, alerting, discovery, and issue docs
scripts/   Development helper scripts

Roadmap

See docs/roadmap.md and docs/gitea-issues.md.

License

MIT