diff --git a/Makefile b/Makefile index 02566bc..77518a3 100644 --- a/Makefile +++ b/Makefile @@ -1,207 +1,249 @@ -# Personal Internet Cell - Makefile -# Provides easy commands for managing the cell - -.PHONY: help start stop restart status logs clean setup check-deps init-peers build build-api build-webui - -# Detect docker compose command (v2 plugin preferred, fallback to v1 standalone) -DC := $(shell docker compose version >/dev/null 2>&1 && echo "docker compose" || echo "docker-compose") - -# Default target -help: - @echo "Personal Internet Cell - Management Commands" - @echo "" - @echo "Setup (run once on a fresh host):" - @echo " setup - Create dirs, generate WireGuard keys, write configs, then: make start" - @echo " Env vars: CELL_NAME=mycell CELL_DOMAIN=cell VPN_ADDRESS=10.0.0.1/24 WG_PORT=51820" - @echo " init-peers - Reset peer list to empty" - @echo "" - @echo "Management:" - @echo " start - Start all services (docker compose up -d)" - @echo " stop - Stop all services" - @echo " restart - Restart all services" - @echo " status - Show container status + API health" - @echo " logs - Follow logs from all services" - @echo "" - @echo "Build:" - @echo " build - Rebuild API image" - @echo " build-api - Rebuild API image (no cache)" - @echo " build-webui - Rebuild Web UI image (no cache)" - @echo "" - @echo "Individual Services:" - @echo " start-dns - Start DNS service only" - @echo " start-api - Start API service only" - @echo " start-wg - Start WireGuard service only" - @echo "" - @echo "Maintenance:" - @echo " clean - Remove all containers and volumes" - @echo " backup - Backup configuration and data" - @echo " restore - Restore from backup" - -# Setup commands -check-deps: - @sudo sh scripts/check_deps.sh - -setup: check-deps - @echo "Setting up Personal Internet Cell..." - @sudo chown -R $$(id -u):$$(id -g) config/ data/ 2>/dev/null || true - CELL_NAME=$(or $(CELL_NAME),mycell) \ - CELL_DOMAIN=$(or $(CELL_DOMAIN),cell) \ - VPN_ADDRESS=$(or $(VPN_ADDRESS),10.0.0.1/24) \ - WG_PORT=$(or $(WG_PORT),51820) \ - WG_PRIVATE_KEY="$(WG_PRIVATE_KEY)" \ - WG_PUBLIC_KEY="$(WG_PUBLIC_KEY)" \ - python3 scripts/setup_cell.py - -init-peers: - @echo "Initializing peer configuration..." - @echo '[]' > data/api/peers.json - @echo "Peer configuration initialized." - -# Management commands -start: - @echo "Starting Personal Internet Cell..." - PUID=$$(id -u) PGID=$$(id -g) $(DC) up -d --build - @echo "Services started. Check status with 'make status'" - -stop: - @echo "Stopping Personal Internet Cell..." - PUID=$$(id -u) PGID=$$(id -g) $(DC) down - @echo "Services stopped." - -restart: - @echo "Restarting Personal Internet Cell..." - PUID=$$(id -u) PGID=$$(id -g) $(DC) restart - @echo "Services restarted." - -status: - @echo "Personal Internet Cell Status:" - @echo "================================" - $(DC) ps - @echo "" - @echo "API Status:" - @curl -s http://localhost:3000/health || echo "API not responding" - -logs: - @echo "Showing logs from all services..." - $(DC) logs -f - -# Individual service commands -start-dns: - @echo "Starting DNS service..." - $(DC) up -d dns - -start-api: - @echo "Starting API service..." - $(DC) up -d api - -start-wg: - @echo "Starting WireGuard service..." - $(DC) up -d wireguard - -start-webui: - @echo "Starting WebUi service..." - $(DC) up -d webui - -# Maintenance commands -clean: - @echo "Cleaning up containers and volumes..." - $(DC) down -v - docker system prune -f - @echo "Cleanup complete." - -backup: - @echo "Creating backup..." - @mkdir -p backups - @tar -czf backups/cell-backup-$(shell date +%Y%m%d-%H%M%S).tar.gz \ - config/ data/ docker-compose.yml Makefile README.md - @echo "Backup created in backups/ directory." - -restore: - @echo "Available backups:" - @ls -la backups/cell-backup-*.tar.gz 2>/dev/null || echo "No backups found" - @echo "" - @echo "To restore, run: tar -xzf backups/cell-backup-YYYYMMDD-HHMMSS.tar.gz" - -# Development commands -dev: - @echo "Starting development environment..." - $(DC) -f docker-compose.yml -f docker-compose.dev.yml up -d - -build: - @echo "Building API service..." - $(DC) build api - -build-api: - @echo "Rebuilding API (no cache)..." - $(DC) build --no-cache api - $(DC) up -d api - -build-webui: - @echo "Rebuilding Web UI (no cache)..." - $(DC) build --no-cache webui - $(DC) up -d webui - -# Testing commands -test: - @echo "Running all unit and integration tests with pytest..." - pytest tests/ api/tests/ - -test-all: - @echo "Running all tests using the unified test runner..." - python3 api/tests/run_tests.py - -# Remove or update old test targets that reference non-existent files -test-unit: - @echo "Running unit tests only..." - pytest tests/ - -test-coverage: - @echo "Running tests with coverage..." - pytest tests/ api/tests/ --cov=api --cov-report=html --cov-report=term-missing -v - -test-api: - @echo "Testing API endpoints..." - cd api && python3 -m pytest tests/test_api_endpoints.py -v - -test-cli: - @echo "Testing CLI tool..." - cd api && python3 -m pytest tests/test_cli_tool.py -v - -test-phase1: - @echo "Testing Phase 1 (Network Foundation)..." - cd api && python3 -m pytest tests/test_network_manager.py tests/test_phase1_endpoints.py -v - -test-phase2: - @echo "Testing Phase 2 (WireGuard & Peer Registry)..." - cd api && python3 -m pytest tests/test_wireguard_manager.py tests/test_phase2_endpoints.py -v - -test-phase3: - @echo "Testing Phase 3 (Core Digital Services)..." - cd api && python3 -m pytest tests/test_phase3_managers.py tests/test_phase3_endpoints.py -v - -test-phase4: - @echo "Testing Phase 4 (VPN Gateway & Routing)..." - cd api && python3 -m pytest tests/test_phase4_routing.py tests/test_phase4_endpoints.py -v - -test-all-phases: - @echo "Testing all phases..." - cd api && python3 -m pytest tests/ -v - -# Network commands -show-routes: - @echo "Current routing table:" - @docker exec cell-wireguard wg show || echo "WireGuard not running" - -add-peer: - @echo "Usage: make add-peer PEER_NAME=name PEER_IP=ip PEER_KEY=public_key" - @if [ -n "$(PEER_NAME)" ] && [ -n "$(PEER_IP)" ] && [ -n "$(PEER_KEY)" ]; then \ - curl -X POST http://localhost:3000/api/peers \ - -H "Content-Type: application/json" \ - -d '{"name":"$(PEER_NAME)","ip":"$(PEER_IP)","public_key":"$(PEER_KEY)"}'; \ - else \ - echo "Please provide PEER_NAME, PEER_IP, and PEER_KEY parameters"; \ - fi - -list-peers: - @echo "Configured peers:" - @curl -s http://localhost:3000/api/peers | python3 -m json.tool || echo "API not responding" \ No newline at end of file +# Personal Internet Cell - Makefile +# Provides easy commands for managing the cell + +.PHONY: help start stop restart status logs clean setup check-deps init-peers \ + update reinstall uninstall \ + build build-api build-webui \ + start-dns start-api start-wg start-webui \ + backup restore \ + test test-all test-unit test-coverage test-api test-cli \ + test-phase1 test-phase2 test-phase3 test-phase4 test-all-phases \ + show-routes add-peer list-peers + +# Detect docker compose command (v2 plugin preferred, fallback to v1 standalone) +DC := $(shell docker compose version >/dev/null 2>&1 && echo "docker compose" || echo "docker-compose") + +# Default target +help: + @echo "Personal Internet Cell - Management Commands" + @echo "" + @echo "First install:" + @echo " check-deps - Install all required system packages (python3, docker, etc.)" + @echo " setup - Generate keys, write configs, create data dirs" + @echo " Env vars: CELL_NAME=mycell CELL_DOMAIN=cell VPN_ADDRESS=10.0.0.1/24 WG_PORT=51820" + @echo " init-peers - Reset peer list to empty" + @echo "" + @echo "Lifecycle:" + @echo " start - Start all services" + @echo " stop - Stop all services" + @echo " restart - Restart all services" + @echo " status - Show container status + API health" + @echo " logs - Follow logs from all services" + @echo " logs- - Follow logs for one service (e.g. make logs-api)" + @echo " shell- - Open shell in a container (e.g. make shell-api)" + @echo "" + @echo "Updates & reinstall:" + @echo " update - git pull + rebuild + restart (deploy latest code)" + @echo " reinstall - Full wipe and fresh install from current git checkout" + @echo " uninstall - Remove containers, images, and all data (keeps git repo)" + @echo "" + @echo "Build:" + @echo " build - Rebuild API image" + @echo " build-api - Rebuild API image (no cache)" + @echo " build-webui - Rebuild Web UI image (no cache)" + @echo "" + @echo "Individual services:" + @echo " start-dns - Start DNS only" + @echo " start-api - Start API only" + @echo " start-wg - Start WireGuard only" + @echo "" + @echo "Maintenance:" + @echo " backup - Backup config + data to backups/" + @echo " restore - List available backups" + @echo " clean - Remove containers and volumes (keeps config/data dirs)" + @echo "" + @echo "Tests:" + @echo " test - Run all tests" + @echo " test-coverage - Run tests with HTML coverage report" + @echo "" + @echo "Peers:" + @echo " list-peers - List configured WireGuard peers" + @echo " show-routes - Show WireGuard routing table" + +# ── Dependencies & setup ────────────────────────────────────────────────────── + +check-deps: + @sudo sh scripts/check_deps.sh + +setup: check-deps + @echo "Setting up Personal Internet Cell..." + @sudo chown -R $$(id -u):$$(id -g) config/ data/ 2>/dev/null || true + CELL_NAME=$(or $(CELL_NAME),mycell) \ + CELL_DOMAIN=$(or $(CELL_DOMAIN),cell) \ + VPN_ADDRESS=$(or $(VPN_ADDRESS),10.0.0.1/24) \ + WG_PORT=$(or $(WG_PORT),51820) \ + WG_PRIVATE_KEY="$(WG_PRIVATE_KEY)" \ + WG_PUBLIC_KEY="$(WG_PUBLIC_KEY)" \ + python3 scripts/setup_cell.py + +init-peers: + @echo "Initializing peer configuration..." + @echo '[]' > data/api/peers.json + @echo "Peer configuration initialized." + +# ── Lifecycle ───────────────────────────────────────────────────────────────── + +start: + @echo "Starting Personal Internet Cell..." + PUID=$$(id -u) PGID=$$(id -g) $(DC) up -d --build + @echo "Services started. Check status with 'make status'" + +stop: + @echo "Stopping Personal Internet Cell..." + PUID=$$(id -u) PGID=$$(id -g) $(DC) down + @echo "Services stopped." + +restart: + @echo "Restarting Personal Internet Cell..." + PUID=$$(id -u) PGID=$$(id -g) $(DC) restart + @echo "Services restarted." + +status: + @echo "Personal Internet Cell Status:" + @echo "================================" + $(DC) ps + @echo "" + @echo "API Status:" + @curl -s http://localhost:3000/health || echo "API not responding" + +logs: + $(DC) logs -f + +logs-%: + $(DC) logs -f $* + +shell-%: + docker exec -it cell-$* /bin/bash 2>/dev/null || docker exec -it cell-$* /bin/sh + +# ── Updates & reinstall ─────────────────────────────────────────────────────── + +update: + @echo "Pulling latest code..." + git pull + @echo "Rebuilding and restarting services..." + PUID=$$(id -u) PGID=$$(id -g) $(DC) up -d --build + @echo "Update complete. Run 'make status' to verify." + +reinstall: + @echo "Reinstalling Personal Internet Cell from scratch..." + PUID=$$(id -u) PGID=$$(id -g) $(DC) down -v 2>/dev/null || true + @sudo rm -rf config/ data/ + @$(MAKE) setup + @$(MAKE) start + @echo "Reinstall complete." + +uninstall: + @echo "Uninstalling Personal Internet Cell..." + PUID=$$(id -u) PGID=$$(id -g) $(DC) down -v --rmi all 2>/dev/null || true + @sudo rm -rf config/ data/ + @echo "Uninstall complete. Git repo and scripts remain." + +# ── Build ───────────────────────────────────────────────────────────────────── + +build: + @echo "Building API service..." + $(DC) build api + +build-api: + @echo "Rebuilding API (no cache)..." + $(DC) build --no-cache api + $(DC) up -d api + +build-webui: + @echo "Rebuilding Web UI (no cache)..." + $(DC) build --no-cache webui + $(DC) up -d webui + +# ── Individual services ─────────────────────────────────────────────────────── + +start-dns: + $(DC) up -d dns + +start-api: + $(DC) up -d api + +start-wg: + $(DC) up -d wireguard + +start-webui: + $(DC) up -d webui + +# ── Maintenance ─────────────────────────────────────────────────────────────── + +clean: + @echo "Removing containers and volumes..." + $(DC) down -v + docker system prune -f + @echo "Done. config/ and data/ are untouched." + +backup: + @echo "Creating backup..." + @mkdir -p backups + @sudo tar -czf backups/cell-backup-$(shell date +%Y%m%d-%H%M%S).tar.gz \ + config/ data/ docker-compose.yml Makefile README.md + @sudo chown $$(id -u):$$(id -g) backups/cell-backup-*.tar.gz + @echo "Backup created in backups/." + +restore: + @echo "Available backups:" + @ls -lh backups/cell-backup-*.tar.gz 2>/dev/null || echo "No backups found." + @echo "" + @echo "To restore: tar -xzf backups/cell-backup-YYYYMMDD-HHMMSS.tar.gz" + +# ── Tests ───────────────────────────────────────────────────────────────────── + +test: + @echo "Running all tests..." + pytest tests/ api/tests/ + +test-all: + python3 api/tests/run_tests.py + +test-unit: + pytest tests/ + +test-coverage: + pytest tests/ api/tests/ --cov=api --cov-report=html --cov-report=term-missing -v + +test-api: + cd api && python3 -m pytest tests/test_api_endpoints.py -v + +test-cli: + cd api && python3 -m pytest tests/test_cli_tool.py -v + +test-phase1: + cd api && python3 -m pytest tests/test_network_manager.py tests/test_phase1_endpoints.py -v + +test-phase2: + cd api && python3 -m pytest tests/test_wireguard_manager.py tests/test_phase2_endpoints.py -v + +test-phase3: + cd api && python3 -m pytest tests/test_phase3_managers.py tests/test_phase3_endpoints.py -v + +test-phase4: + cd api && python3 -m pytest tests/test_phase4_routing.py tests/test_phase4_endpoints.py -v + +test-all-phases: + cd api && python3 -m pytest tests/ -v + +# ── Network / peers ─────────────────────────────────────────────────────────── + +show-routes: + @docker exec cell-wireguard wg show 2>/dev/null || echo "WireGuard not running" + +list-peers: + @curl -s http://localhost:3000/api/peers | python3 -m json.tool || echo "API not responding" + +add-peer: + @if [ -n "$(PEER_NAME)" ] && [ -n "$(PEER_IP)" ] && [ -n "$(PEER_KEY)" ]; then \ + curl -X POST http://localhost:3000/api/peers \ + -H "Content-Type: application/json" \ + -d '{"name":"$(PEER_NAME)","ip":"$(PEER_IP)","public_key":"$(PEER_KEY)"}'; \ + else \ + echo "Usage: make add-peer PEER_NAME=name PEER_IP=10.0.0.x PEER_KEY="; \ + fi + +# ── Dev ─────────────────────────────────────────────────────────────────────── + +dev: + $(DC) -f docker-compose.yml -f docker-compose.dev.yml up -d diff --git a/README.md b/README.md index 5e05bd7..ff33199 100644 --- a/README.md +++ b/README.md @@ -61,8 +61,7 @@ The Personal Internet Cell is a **production-grade, self-hosted, decentralized d ### Prerequisites -- **Docker** with Compose plugin (`docker compose`) or standalone `docker-compose` -- **WireGuard tools** (`wg` binary, for key generation during install) +- **Debian/Ubuntu** host (apt-based). All other dependencies are installed automatically. - **2 GB+ RAM, 10 GB+ disk space** - **Open ports**: 53 (DNS), 80/443 (HTTP/S), 3000 (API), 8081 (Web UI), 51820/udp (WireGuard) @@ -72,16 +71,22 @@ The Personal Internet Cell is a **production-grade, self-hosted, decentralized d git clone pic cd pic -# Default cell (name=mycell, domain=cell, VPN=10.0.0.1/24, port=51820) -make setup && make start +# Install all system dependencies (docker, python3, python3-cryptography, etc.) +make check-deps -# Custom cell — required when installing a second cell on a different host +# Default cell (name=mycell, domain=cell, VPN=10.0.0.1/24, port=51820) +make setup +make start + +# Custom cell — use when installing a second cell on a different host CELL_NAME=pic1 VPN_ADDRESS=10.1.0.1/24 make setup && make start ``` -`make setup` generates WireGuard keys, writes `config/wireguard/wg0.conf` and -`config/api/cell_config.json`, and creates all data directories. -`make start` brings up all 13 Docker containers. +`make check-deps` installs python3, python3-cryptography, docker, docker-compose, curl, openssl, git via apt and adds the current user to the docker group. + +`make setup` generates WireGuard keys, writes configs, and creates all data directories. + +`make start` builds and brings up all 12 Docker containers. ### 2. Access @@ -104,6 +109,41 @@ cd webui && npm install && npm run dev # React UI on :5173 (proxies API to : --- +## 🛠️ Management Commands + +```bash +# First install +make check-deps # install all system packages via apt +make setup # generate keys, write configs +make start # start all 12 containers + +# Daily operations +make status # container status + API health +make logs # follow all logs +make logs-api # follow logs for one service (api, dns, wg, mail, caddy, ...) +make shell-api # open a shell inside a container + +# Deploy latest code +make update # git pull + rebuild + restart + +# Full wipe and reinstall (useful on test machine) +make reinstall # stop, wipe config/data, setup, start fresh + +# Remove everything +make uninstall # stop containers, remove images and all data + +# Maintenance +make backup # tar config/ + data/ into backups/ +make restore # list available backups +make clean # remove containers/volumes, keep config/data + +# Tests +make test # run all tests +make test-coverage # tests + HTML coverage report +``` + +--- + ## 🔗 Connecting Two Cells (PIC Mesh) Two PIC instances can form a mesh — full site-to-site WireGuard tunnels with