feat: add update, reinstall, uninstall, logs-<svc>, shell-<svc> targets

- update: git pull + rebuild + restart
- reinstall: full wipe (config/data) + setup + start
- uninstall: stop, remove images, wipe config/data
- logs-<svc>: follow logs for any single service
- shell-<svc>: exec into any container (bash with sh fallback)
- backup: use sudo tar to read container-owned files
- help: restructured with all commands documented
- README: updated Quick Start + added Management Commands reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Makefile

@@ -1,7 +1,14 @@
 # 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
+.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")
@@ -10,34 +17,51 @@ DC := $(shell docker compose version >/dev/null 2>&1 && echo "docker compose" ||
 help:
 	@echo "Personal Internet Cell - Management Commands"
 	@echo ""
-	@echo "Setup (run once on a fresh host):"
+	@echo "First install:"
-	@echo "  setup          - Create dirs, generate WireGuard keys, write configs, then: make start"
+	@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 "Management:"
+	@echo "Lifecycle:"
-	@echo "  start          - Start all services (docker compose up -d)"
+	@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-<svc>     - Follow logs for one service  (e.g. make logs-api)"
+	@echo "  shell-<svc>    - 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 "Individual services:"
-	@echo "  start-dns      - Start DNS service only"
+	@echo "  start-dns      - Start DNS only"
-	@echo "  start-api      - Start API service only"
+	@echo "  start-api      - Start API only"
-	@echo "  start-wg       - Start WireGuard service only"
+	@echo "  start-wg       - Start WireGuard only"
 	@echo ""
 	@echo "Maintenance:"
-	@echo "  clean          - Remove all containers and volumes"
+	@echo "  backup         - Backup config + data to backups/"
-	@echo "  backup         - Backup configuration and data"
+	@echo "  restore        - List available backups"
-	@echo "  restore        - Restore from backup"
+	@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 ──────────────────────────────────────────────────────
 
-# Setup commands
 check-deps:
 	@sudo sh scripts/check_deps.sh
 
@@ -57,7 +81,8 @@ init-peers:
 	@echo '[]' > data/api/peers.json
 	@echo "Peer configuration initialized."
 
-# Management commands
+# ── Lifecycle ─────────────────────────────────────────────────────────────────
+
 start:
 	@echo "Starting Personal Internet Cell..."
 	PUID=$$(id -u) PGID=$$(id -g) $(DC) up -d --build
@@ -82,50 +107,38 @@ status:
 	@curl -s http://localhost:3000/health || echo "API not responding"
 
 logs:
-	@echo "Showing logs from all services..."
 	$(DC) logs -f
 
-# Individual service commands
+logs-%:
-start-dns:
+	$(DC) logs -f $*
-	@echo "Starting DNS service..."
-	$(DC) up -d dns
 
-start-api:
+shell-%:
-	@echo "Starting API service..."
+	docker exec -it cell-$* /bin/bash 2>/dev/null || docker exec -it cell-$* /bin/sh
-	$(DC) up -d api
 
-start-wg:
+# ── Updates & reinstall ───────────────────────────────────────────────────────
-	@echo "Starting WireGuard service..."
-	$(DC) up -d wireguard
 
-start-webui:
+update:
-	@echo "Starting WebUi service..."
+	@echo "Pulling latest code..."
-	$(DC) up -d webui
+	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."
 
-# Maintenance commands
+reinstall:
-clean:
+	@echo "Reinstalling Personal Internet Cell from scratch..."
-	@echo "Cleaning up containers and volumes..."
+	PUID=$$(id -u) PGID=$$(id -g) $(DC) down -v 2>/dev/null || true
-	$(DC) down -v
+	@sudo rm -rf config/ data/
-	docker system prune -f
+	@$(MAKE) setup
-	@echo "Cleanup complete."
+	@$(MAKE) start
+	@echo "Reinstall complete."
 
-backup:
+uninstall:
-	@echo "Creating backup..."
+	@echo "Uninstalling Personal Internet Cell..."
-	@mkdir -p backups
+	PUID=$$(id -u) PGID=$$(id -g) $(DC) down -v --rmi all 2>/dev/null || true
-	@tar -czf backups/cell-backup-$(shell date +%Y%m%d-%H%M%S).tar.gz \
+	@sudo rm -rf config/ data/
-		config/ data/ docker-compose.yml Makefile README.md
+	@echo "Uninstall complete. Git repo and scripts remain."
-	@echo "Backup created in backups/ directory."
 
-restore:
+# ── Build ─────────────────────────────────────────────────────────────────────
-	@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..."
@@ -141,67 +154,96 @@ build-webui:
 	$(DC) build --no-cache webui
 	$(DC) up -d webui
 
-# Testing commands
+# ── 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 unit and integration tests with pytest..."
+	@echo "Running all tests..."
 	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
+# ── Network / peers ───────────────────────────────────────────────────────────
+
 show-routes:
-	@echo "Current routing table:"
+	@docker exec cell-wireguard wg show 2>/dev/null || echo "WireGuard not running"
-	@docker exec cell-wireguard wg show || echo "WireGuard not running"
+
+list-peers:
+	@curl -s http://localhost:3000/api/peers | python3 -m json.tool || echo "API not responding"
 
 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"; \
+		echo "Usage: make add-peer PEER_NAME=name PEER_IP=10.0.0.x PEER_KEY=<pubkey>"; \
 	fi
 
-list-peers:
+# ── Dev ───────────────────────────────────────────────────────────────────────
-	@echo "Configured peers:"
+
-	@curl -s http://localhost:3000/api/peers | python3 -m json.tool || echo "API not responding" 
+dev:
+	$(DC) -f docker-compose.yml -f docker-compose.dev.yml up -d

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`
+- **Debian/Ubuntu** host (apt-based). All other dependencies are installed automatically.
-- **WireGuard tools** (`wg` binary, for key generation during install)
 - **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 <repo-url> pic
 cd pic
 
-# Default cell (name=mycell, domain=cell, VPN=10.0.0.1/24, port=51820)
+# Install all system dependencies (docker, python3, python3-cryptography, etc.)
-make setup && make start
+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
+`make check-deps` installs python3, python3-cryptography, docker, docker-compose, curl, openssl, git via apt and adds the current user to the docker group.
-`config/api/cell_config.json`, and creates all data directories.
+
-`make start` brings up all 13 Docker containers.
+`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