# Quick Start This guide walks through a first-time PIC installation on a clean Linux host. --- ## Prerequisites - Linux host with the WireGuard kernel module loaded - Docker Engine and Docker Compose installed (v2 plugin or v1 standalone) - Python 3.10+ (for `make setup` only; not needed at runtime) - 2 GB+ RAM, 10 GB+ disk - Ports 53, 80, 443, 51820/udp, 25, 587, 993 available on the host Verify the WireGuard module is available: ```bash sudo modprobe wireguard ``` --- ## 1. Clone the repository ```bash git clone gitea@192.168.31.50:roof/pic.git pic cd pic ``` --- ## 2. Start the stack ```bash make start ``` This builds the `cell-api` and `cell-webui` Docker images and starts all containers. The first run pulls images and compiles the frontend, which takes a few minutes. Check that containers came up: ```bash make status ``` All containers should show as `Up`. --- ## 3. Complete the setup wizard Open a browser and go to: ``` http://:8081 ``` The setup wizard appears automatically on first start. Until the wizard is complete, all API requests redirect to `/setup`. The wizard asks for: - **Cell name** — a short identifier used in hostnames and DDNS. Must start with a lowercase letter and contain only lowercase letters, digits, and hyphens (2–31 characters total). Example: `myhome`. - **Domain mode** — how HTTPS certificates are issued: - `lan` — internal CA, no internet required - `pic_ngo` — automatic `.pic.ngo` subdomain with Let's Encrypt via DNS-01 - `cloudflare` — Let's Encrypt via Cloudflare DNS-01 - `duckdns` — Let's Encrypt via DuckDNS DNS-01 - `http01` — Let's Encrypt via HTTP-01 (no wildcard certificates) - **Timezone** — used for NTP and log timestamps. - **Services to enable** — choose from email, calendar, files, WireGuard. - **Admin password** — at least 12 characters with uppercase, lowercase, and a digit. Click **Complete Setup**. The wizard creates the admin account, writes the cell identity to `config/api/cell_config.json`, and redirects to the login page. --- ## 4. Log in After the wizard, you are redirected to the login page at `/login`. Log in with: - **Username:** `admin` - **Password:** the password you set in the wizard --- ## 5. Add a WireGuard peer Go to **Peers** in the sidebar. 1. Click **Add Peer**. 2. Enter a peer name (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 configuration as a QR code. 5. Scan the QR code with a WireGuard client (Android, iOS, or the WireGuard desktop app). Once connected, `*.cell` names resolve through the cell's CoreDNS and all traffic can be routed through the cell. --- ## 6. Day-to-day operations ```bash # Check container status and API health make status # Follow logs from all services make logs # Follow logs from a single service make logs-api make logs-wireguard make logs-caddy # Open a shell inside a container make shell-api make shell-dns ``` --- ## 7. 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 ``` --- ## 8. 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 on a new machine with no data), it runs `make setup` first to generate directory structure and base config files. --- ## 9. Uninstalling ```bash make uninstall ``` This stops and removes all containers, then prompts: - **y** — also deletes `config/` and `data/` (full wipe; cannot be undone) - **n** (default) — stops containers but leaves images, `config/`, and `data/` intact; `make start` will bring everything back The systemd unit (`pic.service`) is disabled and removed either way. --- ## Troubleshooting ### Containers not starting ```bash make logs make logs-api ``` Look for errors about missing config files or port conflicts. ### Port 53 already in use On Ubuntu and 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. ### WireGuard container fails to load the kernel module ```bash sudo modprobe wireguard ``` On minimal installs you may need to install `wireguard-tools` and the kernel headers for the running kernel before `modprobe` succeeds. ### API returns 428 and redirects to /setup The first-run wizard has not been completed. Open `http://:8081` and finish the wizard. ### API returns 401 or the UI shows "Not authenticated" Your session has expired or you have not logged in yet. Go to `http://:8081/login`. ### API returns 503 with "Authentication not configured" The `users` file exists but contains no accounts. This should not happen after a normal wizard completion. To recover: ```bash make reset-admin-password ``` This generates a new admin password and prints it to the terminal. ### API returns 503 or the 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. Click **Apply Now** to restart the affected containers with the new configuration. ### Forgot the admin password ```bash make show-admin-password ``` If that doesn't help (e.g. the setup data file is missing): ```bash make reset-admin-password ```