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

Update QUICKSTART: lead with curl installer, document all domain modes
Unit Tests / test (push) Failing after 8m43s
Details

Browse Source 
Option A is now the one-line curl installer (install.pic.ngo); Option B
is the manual git clone path. Wizard section covers all five domain modes
(pic_ngo, cloudflare, duckdns, http01, lan) and current password rules.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Dmitrii Iurco
2026-05-10 05:05:08 -04:00
parent 35993bc79d
commit 515f3d5075
1 changed files with 67 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
QUICKSTART.md
+67 -100
View File
@@ -6,86 +6,88 @@ This guide walks through a first-time PIC installation on a clean Linux host.
## Prerequisites ## Prerequisites
- Linux host with the WireGuard kernel module loaded - Linux x86-64 host — Debian, Ubuntu, Fedora, RHEL, or Alpine
- 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 - 2 GB+ RAM, 10 GB+ disk
- Ports 53, 80, 443, 51820/udp, 25, 587, 993 available on the host - Ports 53, 80, 443, 51820/udp, 25, 587, 993 available
Verify the WireGuard module is available: The installer handles all software dependencies (git, docker, make, etc.) automatically.
---
## Option A — One-line installer (recommended)
```bash ```bash
sudo modprobe wireguard curl -fsSL https://install.pic.ngo | sudo bash
```
Always review the script before running it:
```bash
curl -fsSL https://install.pic.ngo | less
```
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
When it finishes, open the URL it prints:
```
http://<host-ip>:8081/setup
``` ```
--- ---
## 1. Clone the repository ## Option B — Manual install
Use this if you want to control where PIC is installed, or if you are installing on a machine that already has Docker.
```bash ```bash
git clone gitea@192.168.31.50:roof/pic.git pic git clone https://git.pic.ngo/roof/pic.git pic
cd pic cd pic
sudo make install
make start-core
``` ```
Then open `http://<host-ip>:8081` in a browser.
--- ---
## 2. Start the stack ## Complete the setup wizard
```bash The setup wizard appears automatically on first start. All API requests redirect to `/setup` until it is finished.
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: 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`. - **Cell name** — used for hostnames and DDNS subdomain. Lowercase letters, digits, hyphens, 2–31 characters. Example: `myhome`.
- **Domain mode** — how HTTPS certificates are issued: - **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 (recommended for internet-facing cells)
- `pic_ngo` — automatic `<cell-name>.pic.ngo` subdomain with Let's Encrypt via DNS-01 - `cloudflare` — Let's Encrypt via Cloudflare DNS-01 (bring your own domain)
- `cloudflare` — Let's Encrypt via Cloudflare DNS-01
- `duckdns` — Let's Encrypt via DuckDNS DNS-01 - `duckdns` — Let's Encrypt via DuckDNS DNS-01
- `http01` — Let's Encrypt via HTTP-01 (no wildcard certificates) - `http01` — Let's Encrypt via HTTP-01 (no wildcard; cell must be reachable on port 80)
- **Timezone** — used for NTP and log timestamps. - `lan` — internal CA, no internet required (for LAN-only installs)
- **Services to enable** — choose from email, calendar, files, WireGuard. - **Timezone**
- **Admin password** — at least 12 characters with uppercase, lowercase, and a digit. - **Services to enable** — email, calendar, files, WireGuard
- **Admin password** — minimum 12 characters, must contain 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. Click **Complete Setup**. The wizard creates the admin account, writes cell identity to `config/api/cell_config.json`, and redirects to the login page.
--- ---
## 4. Log in ## Log in
After the wizard, you are redirected to the login page at `/login`. After the wizard you are redirected to `/login`.
Log in with:
- **Username:** `admin` - **Username:** `admin`
- **Password:** the password you set in the wizard - **Password:** the password you set in the wizard
--- ---
## 5. Add a WireGuard peer ## Add a WireGuard peer
Go to **Peers** in the sidebar. Go to **Peers** in the sidebar.
@@ -95,11 +97,11 @@ Go to **Peers** in the sidebar.
4. Click the QR code icon to display the peer configuration 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). 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. Once connected, `*.cell` names resolve through the cell's CoreDNS and traffic can be routed through the cell.
--- ---
## 6. Day-to-day operations ## Day-to-day operations
```bash ```bash
# Check container status and API health # Check container status and API health
@@ -120,20 +122,11 @@ make shell-dns
--- ---
## 7. Backup ## Backup and restore
Before making significant changes, create a backup:
```bash ```bash
make backup make backup # archives config/ and data/ into backups/cell-backup-<timestamp>.tar.gz
``` make restore # list available backups
This archives `config/` and `data/` into `backups/cell-backup-<timestamp>.tar.gz`.
To list available backups:
```bash
make restore
``` ```
To restore manually: To restore manually:
@@ -145,29 +138,20 @@ make start
--- ---
## 8. Updating PIC ## Updating PIC
```bash ```bash
make update make update # git pull + rebuild + restart
``` ```
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 ## Uninstalling
```bash ```bash
make uninstall make uninstall # stops containers; prompts to also delete config/ and data/
``` ```
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 ## Troubleshooting
@@ -199,46 +183,29 @@ Then run `make start` again.
sudo modprobe wireguard sudo modprobe wireguard
``` ```
On minimal installs you may need to install `wireguard-tools` and the kernel headers for the running kernel before `modprobe` succeeds. On minimal installs you may need `wireguard-tools` and the kernel headers for the running kernel.
### API returns 428 and redirects to /setup ### API returns 428 and redirects to /setup
The first-run wizard has not been completed. Open `http://<host-ip>:8081` and finish the wizard. 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" ### API returns 401 / UI shows "Not authenticated"
Your session has expired or you have not logged in yet. Go to `http://<host-ip>:8081/login`. Your session expired or you have not logged in. Go to `http://<host-ip>:8081/login`.
### API returns 503 with "Authentication not configured" ### API returns 503 "Authentication not configured"
The `users` file exists but contains no accounts. This should not happen after a normal wizard completion. To recover: The auth file exists but contains no accounts. To recover:
```bash ```bash
make reset-admin-password make reset-admin-password
``` ```
This generates a new admin password and prints it to the terminal. This generates a new admin password and prints it.
### 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 ### Forgot the admin password
```bash ```bash
make show-admin-password make show-admin-password # print current password
``` make reset-admin-password # generate a new random password
If that doesn't help (e.g. the setup data file is missing):
```bash
make reset-admin-password
``` ```