docs: bring all docs current with this session's changes
Unit Tests / test (push) Successful in 12m12s
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:
+31
-13
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user