roof
35993bc79d
Unit Tests / test (push) Failing after 8m47s
README, QUICKSTART, and Wiki were pre-wizard, pre-auth, pre-DDNS, and pre-service-store. Full rewrite covering: - First-run wizard replaces manual make setup + .env identity config - Session-based auth (admin/peer roles, CSRF protection) - DDNS: pic.ngo registration with TOTP, provider abstraction - Service store: install/remove optional services from manifest index - Cell-to-cell networking and peer-sync protocol - Extended connectivity: WG external, OpenVPN, Tor exit routing - Caddy HTTPS: Let's Encrypt (DNS-01/HTTP-01) or internal CA - Current container list, port bindings, and security model - Accurate make targets (ddns-update, reset-admin-password, etc.) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
245 lines
5.7 KiB
Markdown
245 lines
5.7 KiB
Markdown
# 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://<host-ip>: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 `<cell-name>.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-<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
|
||
```
|
||
|
||
---
|
||
|
||
## 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://<host-ip>: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://<host-ip>: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
|
||
```
|