# 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 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://: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= ``` --- ## 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-.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.