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>
This commit is contained in:
@@ -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 " setup - Create dirs, generate WireGuard keys, write configs, then: make start"
|
||||
@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 "Management:"
|
||||
@echo " start - Start all services (docker compose up -d)"
|
||||
@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-<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 " start-dns - Start DNS service only"
|
||||
@echo " start-api - Start API service only"
|
||||
@echo " start-wg - Start WireGuard service only"
|
||||
@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 " clean - Remove all containers and volumes"
|
||||
@echo " backup - Backup configuration and data"
|
||||
@echo " restore - Restore from backup"
|
||||
@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 ──────────────────────────────────────────────────────
|
||||
|
||||
# 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
|
||||
start-dns:
|
||||
@echo "Starting DNS service..."
|
||||
$(DC) up -d dns
|
||||
logs-%:
|
||||
$(DC) logs -f $*
|
||||
|
||||
start-api:
|
||||
@echo "Starting API service..."
|
||||
$(DC) up -d api
|
||||
shell-%:
|
||||
docker exec -it cell-$* /bin/bash 2>/dev/null || docker exec -it cell-$* /bin/sh
|
||||
|
||||
start-wg:
|
||||
@echo "Starting WireGuard service..."
|
||||
$(DC) up -d wireguard
|
||||
# ── Updates & reinstall ───────────────────────────────────────────────────────
|
||||
|
||||
start-webui:
|
||||
@echo "Starting WebUi service..."
|
||||
$(DC) up -d webui
|
||||
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."
|
||||
|
||||
# Maintenance commands
|
||||
clean:
|
||||
@echo "Cleaning up containers and volumes..."
|
||||
$(DC) down -v
|
||||
docker system prune -f
|
||||
@echo "Cleanup complete."
|
||||
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."
|
||||
|
||||
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."
|
||||
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."
|
||||
|
||||
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 ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
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 || echo "WireGuard not running"
|
||||
@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:
|
||||
@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:
|
||||
@echo "Configured peers:"
|
||||
@curl -s http://localhost:3000/api/peers | python3 -m json.tool || echo "API not responding"
|
||||
# ── Dev ───────────────────────────────────────────────────────────────────────
|
||||
|
||||
dev:
|
||||
$(DC) -f docker-compose.yml -f docker-compose.dev.yml up -d
|
||||
|
||||
@@ -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 <repo-url> 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
|
||||
|
||||
Reference in New Issue
Block a user