docs: bring all docs current with this session's changes
Unit Tests / test (push) Successful in 12m12s

Update README, QUICKSTART, wiki, service-developer-guide, and CLAUDE.md for:
optional store services (email/calendar/files), sshuttle+proxy egress exits,
provider-aware Network Services/DNS overview, DHCP/dnsmasq removal, split-horizon
VPN DNS, container hardening (slim images, unprivileged WireGuard, webui port 8080,
pinned ntp/coredns), installer changes (host NTP, PIC_DEBUG, clean output, systemd),
and the backup overhaul (full secrets coverage + optional passphrase encryption).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-10 15:56:03 -04:00
parent 82a0c0e9bd
commit 8a9f4f50c6
5 changed files with 196 additions and 67 deletions
+31 -13
View File
@@ -10,6 +10,7 @@ This guide walks through a first-time PIC installation on a clean Linux host.
- 2 GB+ RAM, 10 GB+ disk
- Always-required ports: 53, 80, 443, 51820/udp
- Email service only (when installed): 25, 587, 993
- WireGuard kernel module available on the host (`modprobe wireguard`); required — userspace WireGuard is not supported
The installer handles all software dependencies (git, docker, make, etc.) automatically.
@@ -27,13 +28,16 @@ Always review the script before running it:
curl -fsSL https://install.pic.ngo | less
```
The installer runs 7 steps and prints clean one-line progress for each. Run with `PIC_DEBUG=1` or `--debug` for full verbose output. A complete log is always written to `/var/log/pic-install.log`.
The installer:
1. Detects your OS and installs Docker, git, make via the system package manager
2. Creates a `pic` system user and adds it to the `docker` group
3. Clones the repository to `/opt/pic`
4. Runs `make install` (generates keys and config, writes a systemd unit)
5. Runs `make start-core` to bring up the core containers
6. Waits for the API to respond, then prints the wizard URL
2. Installs and starts host NTP (chrony) — required for ACME certificate issuance and DDNS token registration
3. Creates a `pic` system user and adds it to the `docker` group
4. Clones the repository to `/opt/pic`
5. Runs `make install` — generates keys and config, writes a systemd unit. The admin password is printed once here; it does not appear again.
6. Runs `make start-core` to bring up the six core containers
7. Enables the `pic` systemd unit so the stack starts on reboot, then waits for the API health check
When it finishes, open the URL it prints:
@@ -54,7 +58,13 @@ sudo make install
make start-core
```
Then open `http://<host-ip>:8081` in a browser.
Then open `http://<host-ip>:8081/setup` in a browser.
Note: install host NTP before running `make install` if you plan to use `pic_ngo` domain mode. The installer does this automatically in Option A.
```bash
sudo apt-get install -y chrony && sudo systemctl enable --now chrony
```
---
@@ -66,11 +76,11 @@ The wizard asks for:
- **Cell name** — used for hostnames and DDNS subdomain. Lowercase letters, digits, hyphens, 2–31 characters. Example: `myhome`.
- **Domain mode** — how HTTPS certificates are issued:
- `pic_ngo` — automatic `<cell-name>.pic.ngo` subdomain with Let's Encrypt via DNS-01 (recommended for internet-facing cells)
- `cloudflare` — Let's Encrypt via Cloudflare DNS-01 (bring your own domain)
- `pic_ngo` — automatic `<cell-name>.pic.ngo` subdomain with a wildcard Let's Encrypt cert via DNS-01 (recommended for internet-facing cells; requires accurate host clock)
- `cloudflare` wildcard Let's Encrypt cert via Cloudflare DNS-01 (bring your own domain)
- `duckdns` — Let's Encrypt via DuckDNS DNS-01
- `http01` — Let's Encrypt via HTTP-01 (no wildcard; cell must be reachable on port 80)
- `lan` — internal CA, no internet required (for LAN-only installs)
- `lan` — internal CA only, no internet required (for LAN-only installs)
- **Timezone**
- **Services to install** — email, calendar, files (optional; installed in the background after setup completes; can be added later via the Services store page)
- **Admin password** — minimum 12 characters, must contain uppercase, lowercase, and a digit
@@ -155,13 +165,19 @@ make backup # archives config/ and data/ into backups/cell-backup-<timestam
make restore # list available backups
```
To restore manually:
The backup archive is written mode `0600`. It contains secrets and key material — WireGuard keys, the internal CA, vault keys, admin credentials, DDNS token, cell links, and Caddy certificates. Store it securely.
Data volumes for installed store services (email mailboxes, calendar data, file storage) are captured separately via the API-driven backup (`POST /api/config/backup`), which also supports an optional passphrase for encryption at rest. The encrypted file is named `<backup_id>.tar.gz.age`.
To restore from a `make backup` archive:
```bash
tar -xzf backups/cell-backup-YYYYMMDD-HHMMSS.tar.gz
make start
make restart
```
After restore, the API re-generates the Caddyfile and Corefile from the restored config and re-applies routing rules automatically.
---
## Updating PIC
@@ -203,13 +219,15 @@ echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
Then run `make start` again.
### WireGuard container fails to load the kernel module
### WireGuard container fails to start
The WireGuard container runs unprivileged (NET_ADMIN only, no privileged mode). It requires the host kernel's WireGuard module — either compiled in (Linux 5.6+) or loadable.
```bash
sudo modprobe wireguard
```
On minimal installs you may need `wireguard-tools` and the kernel headers for the running kernel.
On minimal installs you may need `wireguard-tools` and the kernel headers for the running kernel. On kernels that lack a builtin WireGuard module, check your distro's `wireguard-dkms` or `wireguard-linux-compat` package.
### API returns 428 and redirects to /setup