roof
a338836bb8
Security fixes: - Replace debug=True with env-driven FLASK_DEBUG in app.py - Add _safe_path helper and path-traversal protection to all 6 file routes in file_manager.py - Add peer_name regex and input validation (public_key, name, endpoint_ip) in wireguard_manager.py - Stop returning private key from GET /api/wireguard/keys; return only public_key + has_private_key boolean - Fix is_local_request() XFF bypass by checking remote_addr only, ignoring X-Forwarded-For - Remove duplicate get_all_configs / get_config_summary methods from config_manager.py DevOps: - Bind 6 internal service ports to 127.0.0.1 in docker-compose.yml (radicale, webdav, api, webui, rainloop, filegator) - Move WebDAV credentials to env vars (WEBDAV_USER, WEBDAV_PASS) - Pin flask, flask-cors, requests, cryptography, docker to secure minimum versions in requirements.txt QA (560 tests, 0 failures): - tests/test_wireguard_endpoints.py: 18 new endpoint tests - tests/test_file_endpoints.py: 24 new endpoint tests incl. path traversal - tests/test_container_manager.py: expanded from 2 to 30 tests - tests/test_config_backup_restore_http.py: 25 new tests (new file) - tests/test_config_apply.py: 9 new tests (new file) Docs: - Rewrite README.md with accurate architecture, ports, env vars, security notes - Rewrite QUICKSTART.md with verified commands Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
5.0 KiB
Quick Start
This guide walks through a first-time PIC installation from a clean Linux host.
Prerequisites
- Linux host with the WireGuard kernel module (
modprobe wireguardto verify) - Docker Engine and Docker Compose installed
- Python 3.10+ (needed for
make setuponly) - 2 GB+ RAM, 10 GB+ disk
1. Clone the repository
git clone <repo-url> pic
cd pic
2. Configure the environment
Copy the example environment file and edit it:
cp .env.example .env
Open .env and set at minimum:
WEBDAV_PASS=changeme
WEBDAV_PASS must be set before starting — the WebDAV container will fail to start without it.
All other variables have working defaults. See the Configuration section in README.md for the full list.
3. Run setup
make setup installs system dependencies, generates WireGuard keys, and writes all required config files under config/:
make check-deps # installs docker, python3-cryptography, etc. via apt
make setup # generates keys and writes configs
To customise the cell identity at setup time, pass overrides on the command line:
CELL_NAME=myhome CELL_DOMAIN=cell VPN_ADDRESS=10.0.0.1/24 WG_PORT=51820 make setup
VPN_ADDRESS must be an RFC-1918 address (e.g. 10.0.0.1/24).
4. Start the stack
make start
This builds the cell-api and cell-webui images and starts all 13 containers. The first run takes a few minutes while images are pulled and built.
Check that everything came up:
make status
You should see all containers in the Up state and the API responding at http://localhost:3000/health.
5. Open the web UI
Open a browser and go to:
http://<host-ip>:8081
If you are running locally:
http://localhost:8081
The sidebar contains: Dashboard, Peers, Network Services, WireGuard, Email, Calendar, Files, Routing, Vault, Containers, Cell Network, Logs, Settings.
6. Set cell identity
Go to Settings in the sidebar.
Set your:
- Cell name — a short identifier, e.g.
myhome - Domain — the TLD your cell will use internally, e.g.
cell - VPN IP range — the CIDR for WireGuard peers, e.g.
10.0.0.0/24
After saving, the UI will show a banner asking you to apply the changes. Click Apply Now. The containers will restart briefly to pick up the new configuration.
7. Add a WireGuard peer
Go to WireGuard in the sidebar.
- Click Add Peer.
- Enter a name for the peer (e.g.
laptop). - The API generates a key pair and assigns the next available VPN IP automatically.
- Click the QR code icon to display the peer config as a QR code.
- Scan the QR code with a WireGuard client (Android, iOS, or the WireGuard desktop app).
The peer config sets your cell as the DNS server. Once connected, *.cell names resolve through the cell's CoreDNS.
To manage peers from the command line:
make list-peers
make add-peer PEER_NAME=phone PEER_IP=10.0.0.3 PEER_KEY=<base64-pubkey>
8. Day-to-day operations
# Follow logs from all services
make logs
# Follow logs from a single service
make logs-api
make logs-wireguard
make logs-caddy
# Check container status and API health
make status
# Open a shell inside a container
make shell-api
make shell-dns
9. Backup
Before making significant changes, create a backup:
make backup
This archives config/ and data/ into backups/cell-backup-<timestamp>.tar.gz.
To list available backups:
make restore
To restore manually:
tar -xzf backups/cell-backup-YYYYMMDD-HHMMSS.tar.gz
make start
Backup and restore is also available in the UI under Settings.
10. Updating PIC
make update
This runs git pull, then rebuilds and restarts all containers. If config/ is missing (e.g. after a fresh clone), it runs make setup automatically.
Troubleshooting
Containers not starting
make logs
make logs-api
Look for errors related to missing config files or port conflicts.
Port 53 already in use
On Ubuntu/Debian, systemd-resolved listens on port 53. Disable it:
sudo systemctl disable --now systemd-resolved
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
Then run make start again.
WebDAV container exits immediately
WEBDAV_PASS is not set in .env. Set it and run make start again.
WireGuard container fails to load kernel module
Ensure the WireGuard kernel module is available:
sudo modprobe wireguard
On some minimal installs you may need to install wireguard-tools and the kernel headers for your running kernel.
API returns 503 or UI shows "Backend Unavailable"
The Flask API may still be starting. Wait 10–15 seconds after make start and refresh. If it persists:
make logs-api
Config changes not taking effect
After changing identity or service settings in the UI, a yellow banner appears at the top of the page. Click Apply Now to restart the affected containers.