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>
240 lines
5.0 KiB
Markdown
240 lines
5.0 KiB
Markdown
# 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 wireguard` to verify)
|
||
- Docker Engine and Docker Compose installed
|
||
- Python 3.10+ (needed for `make setup` only)
|
||
- 2 GB+ RAM, 10 GB+ disk
|
||
|
||
---
|
||
|
||
## 1. Clone the repository
|
||
|
||
```bash
|
||
git clone <repo-url> pic
|
||
cd pic
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Configure the environment
|
||
|
||
Copy the example environment file and edit it:
|
||
|
||
```bash
|
||
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](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/`:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|
||
|
||
1. Click **Add Peer**.
|
||
2. Enter a name for the peer (e.g. `laptop`).
|
||
3. The API generates a key pair and assigns the next available VPN IP automatically.
|
||
4. Click the QR code icon to display the peer config as a QR code.
|
||
5. 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:
|
||
|
||
```bash
|
||
make list-peers
|
||
make add-peer PEER_NAME=phone PEER_IP=10.0.0.3 PEER_KEY=<base64-pubkey>
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Day-to-day operations
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
make backup
|
||
```
|
||
|
||
This archives `config/` and `data/` into `backups/cell-backup-<timestamp>.tar.gz`.
|
||
|
||
To list available backups:
|
||
|
||
```bash
|
||
make restore
|
||
```
|
||
|
||
To restore manually:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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**
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|