roof/pic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update all documentation to reflect current architecture
Unit Tests / test (push) Failing after 8m47s
Details

Browse Source 
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>
This commit is contained in:
Dmitrii Iurco
2026-05-10 04:35:37 -04:00
parent f1b48208fc
commit 35993bc79d
3 changed files with 540 additions and 690 deletions
Download Patch File Download Diff File Expand all files Collapse all files
QUICKSTART.md
+102 -97
View File
@@ -1,85 +1,53 @@
# Quick Start
This guide walks through a first-time PIC installation from a clean Linux host.
This guide walks through a first-time PIC installation on 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)
- 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 <repo-url> pic
git clone gitea@192.168.31.50:roof/pic.git 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
## 2. 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.
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 everything came up:
Check that containers came up:
```bash
make status
```
You should see all containers in the `Up` state and the API responding at `http://localhost:3000/health`.
All containers should show as `Up`.
---
## 5. Open the web UI
## 3. Complete the setup wizard
Open a browser and go to:
@@ -87,53 +55,56 @@ Open a browser and go to:
http://<host-ip>:8081
```
If you are running locally:
The setup wizard appears automatically on first start. Until the wizard is complete, all API requests redirect to `/setup`.
```
http://localhost:8081
```
The wizard asks for:
The sidebar contains: Dashboard, Peers, Network Services, WireGuard, Email, Calendar, Files, Routing, Vault, Containers, Cell Network, Logs, Settings.
- **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.
---
## 6. Set cell identity
## 4. Log in
Go to **Settings** in the sidebar.
After the wizard, you are redirected to the login page at `/login`.
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`
Log in with:
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.
- **Username:** `admin`
- **Password:** the password you set in the wizard
---
## 7. Add a WireGuard peer
## 5. Add a WireGuard peer
Go to **WireGuard** in the sidebar.
Go to **Peers** in the sidebar.
1. Click **Add Peer**.
2. Enter a name for the peer (e.g. `laptop`).
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 config as a QR code.
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).
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>
```
Once connected, `*.cell` names resolve through the cell's CoreDNS and all traffic can be routed through the cell.
---
## 8. Day-to-day operations
## 6. Day-to-day operations
```bash
# Check container status and API health
make status
# Follow logs from all services
make logs
@@ -142,9 +113,6 @@ 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
@@ -152,7 +120,7 @@ make shell-dns
---
## 9. Backup
## 7. Backup
Before making significant changes, create a backup:
@@ -175,34 +143,47 @@ 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
## 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), it runs `make setup` automatically.
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**
### Containers not starting
```bash
make logs
make logs-api
```
Look for errors related to missing config files or port conflicts.
Look for errors about missing config files or port conflicts.
**Port 53 already in use**
### Port 53 already in use
On Ubuntu/Debian, `systemd-resolved` listens on port 53. Disable it:
On Ubuntu and Debian, `systemd-resolved` listens on port 53. Disable it:
```bash
sudo systemctl disable --now systemd-resolved
@@ -212,21 +193,33 @@ 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:
### WireGuard container fails to load the kernel module
```bash
sudo modprobe wireguard
```
On some minimal installs you may need to install `wireguard-tools` and the kernel headers for your running kernel.
On minimal installs you may need to install `wireguard-tools` and the kernel headers for the running kernel before `modprobe` succeeds.
**API returns 503 or UI shows "Backend Unavailable"**
### 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:
@@ -234,6 +227,18 @@ The Flask API may still be starting. Wait 10–15 seconds after `make start` and
make logs-api
```
**Config changes not taking effect**
### 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.
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
```