roof
e79ee08c63
- Fix CoreDNS not loading .cell zones (wrong Corefile path, now uses -conf flag) - Fix WireGuard server address conflict (172.20.0.1/16 overlapped with Docker network; changed to 10.0.0.1/24 to eliminate duplicate routes) - Add SERVERMODE=true and sysctls to WireGuard docker-compose for server mode - Fix DNS zone file parser to handle 4-field records (name IN type value) - Add get_dns_records() to NetworkManager; mount data/dns into API container - Fix peer config endpoint: look up IP/key from registry, use real endpoint - Add bulk peer statuses endpoint keyed by public_key - Normalize snake_case API fields to camelCase in WireGuard UI - Add port check endpoint (checks via live handshake, not unreliable TCP probe) - Add Caddy virtual hosts for ui/calendar/files/mail .cell domains (HTTP only) - Fix cell config domain default from cell.local to cell - Fix Routing Network Config tab (was calling hardcoded localhost:3000) - Fix DNS records display (record.value not record.ip) - Move service access guide to top of Dashboard with login hints - Add /api/routing/setup endpoint Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
77 lines
3.9 KiB
Markdown
77 lines
3.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What This Project Is
|
|
|
|
**Personal Internet Cell (PIC)** — a self-hosted digital infrastructure platform. It manages DNS, DHCP, NTP, WireGuard VPN, email, calendar/contacts (CalDAV), file storage (WebDAV), reverse proxy (Caddy), a certificate authority, and container orchestration, all from a single API + React UI.
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Full stack
|
|
make start # docker-compose up -d
|
|
make stop # docker-compose down
|
|
make restart # docker-compose restart
|
|
make status # docker status + API health
|
|
make logs # docker-compose logs -f
|
|
make build # rebuild api image
|
|
|
|
# Tests
|
|
make test # pytest tests/ api/tests/
|
|
make test-coverage # pytest with coverage HTML report
|
|
make test-api # pytest tests/test_api_endpoints.py
|
|
pytest tests/test_<module>.py # single test file
|
|
|
|
# Local dev (no Docker)
|
|
pip install -r api/requirements.txt
|
|
python api/app.py # Flask API on :3000
|
|
|
|
cd webui && npm install && npm run dev # React UI on :5173 (proxies API to :3000)
|
|
|
|
# WireGuard
|
|
make show-routes
|
|
make add-peer PEER_NAME=foo PEER_IP=10.0.0.5 PEER_KEY=<pubkey>
|
|
make list-peers
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Backend (`api/`)
|
|
|
|
All service managers inherit `BaseServiceManager` (`api/base_service_manager.py`). This enforces a consistent interface: `get_status()`, `get_config()`, `update_config()`, `validate_config()`, `test_connectivity()`, `get_logs()`, `restart_service()`. When adding or modifying a service manager, follow this pattern.
|
|
|
|
The `ServiceBus` (`api/service_bus.py`) is a pub/sub event system used for inter-service communication. Services publish events (e.g., `SERVICE_STARTED`, `CONFIG_CHANGED`, `PEER_CONNECTED`) and subscribe to events from dependencies. Dependency graph is declared in the bus — e.g., `wireguard` depends on `network`; `email` depends on `network` and `vault`.
|
|
|
|
`ConfigManager` (`api/config_manager.py`) is the single source of truth. Config lives in `/app/config/cell_config.json` (mapped from `config/api/`). All managers read/write through ConfigManager, which validates against per-service schemas and maintains automatic backups.
|
|
|
|
`LogManager` (`api/log_manager.py`) provides structured JSON logging with rotation (5 MB / 5 backups per service). Use it instead of `print()` or raw `logging`.
|
|
|
|
`app.py` (2000+ lines) contains all Flask REST endpoints, organized by service. It runs a background health-monitoring thread.
|
|
|
|
Service managers:
|
|
- `network_manager.py` — DNS (CoreDNS), DHCP (dnsmasq), NTP (chrony)
|
|
- `wireguard_manager.py` — VPN peer lifecycle, QR codes
|
|
- `peer_registry.py` — peer registration/lookup
|
|
- `routing_manager.py` — NAT, firewall rules, VPN gateway
|
|
- `vault_manager.py` — internal certificate authority
|
|
- `email_manager.py` — Postfix + Dovecot
|
|
- `calendar_manager.py` — Radicale CalDAV/CardDAV
|
|
- `file_manager.py` — WebDAV storage
|
|
- `container_manager.py` — Docker SDK wrappers
|
|
- `cell_manager.py` — top-level orchestration
|
|
|
|
### Frontend (`webui/`)
|
|
|
|
React 18 + Vite + Tailwind CSS. All API calls go through `src/services/api.js` (Axios). Vite dev server proxies `/api` to `localhost:3000`. Pages in `src/pages/`, shared components in `src/components/`.
|
|
|
|
### Infrastructure
|
|
|
|
`docker-compose.yml` defines 13 services on a custom bridge network `cell-network` (172.20.0.0/16). Cell IPs default to 10.0.0.0/24. Key ports: 53 (DNS), 80/443 (Caddy), 3000 (API), 5173/8081 (WebUI), 51820/udp (WireGuard), 25/587/993 (mail), 5232 (CalDAV), 8080 (WebDAV).
|
|
|
|
Config files for each service live under `config/<service>/`. Persistent data is under `data/` (git-ignored). WireGuard configs are also git-ignored.
|
|
|
|
## Testing
|
|
|
|
Tests live in `tests/` (28 files). Use mocking (`pytest-mock`) for external system calls. Integration tests in `test_integration.py` require Docker services running.
|