Overseer is a homelab control plane consisting of three main components:
- Core - API server and web UI
- Agent - Node agent that executes tasks
- Integrations - Third-party service integrations
- Technology: Node.js with Express or Go
- Database: PostgreSQL (via Prisma)
- Queue: Redis with BullMQ
- Responsibilities:
- API endpoints for management
- State management and persistence
- Job queuing and orchestration
- Integration with external services
- Technology: React + Vite + TypeScript
- UI Framework: Tailwind CSS
- State Management: Zustand + React Query
- Responsibilities:
- User interface for all operations
- Real-time status updates
- Dashboard and monitoring views
- Technology: Go
- Responsibilities:
- Register with core and send heartbeats
- Execute Docker Compose deployments
- Stream container logs
- Generate Traefik configurations
- Run backup jobs
- Collect metrics
- User creates app via UI → Core API
- Core API stores app definition in PostgreSQL
- Core API creates deployment job in Redis queue
- Agent pulls job from queue
- Agent deploys app via Docker Compose
- Agent updates app status in Core API
- Core API generates Traefik route configuration
- Core API creates Cloudflare DNS record
- App becomes accessible at configured domain
- Docker: Direct API access for container management
- Traefik: File provider for dynamic route configuration
- Cloudflare: API for DNS and Tunnel management
- Proxmox: REST API for VM/LXC management
- Prometheus: Metrics collection
- Loki: Log aggregation