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
- 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)
- Linux x86-64 host — Debian, Ubuntu, Fedora, RHEL, or Alpine
- 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
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
git clone gitea@192.168.31.50:roof/pic.git pic
git clone https://git.pic.ngo/roof/pic.git 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
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 setup wizard appears automatically on first start. All API requests redirect to `/setup` until it is finished.
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:
- `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
- `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)
- `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.
- `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)
- **Timezone**
- **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`.
Log in with:
After the wizard you are redirected to `/login`.
- **Username:** `admin`
- **Password:** the password you set in the wizard
---
## 5. Add a WireGuard peer
## Add a WireGuard peer
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.
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
# Check container status and API health
@@ -120,20 +122,11 @@ make shell-dns
---
## 7. Backup
Before making significant changes, create a backup:
## Backup and restore
```bash
make backup
```
This archives `config/` and `data/` into `backups/cell-backup-<timestamp>.tar.gz`.
To list available backups:
```bash
make restore
make backup # archives config/ and data/ into backups/cell-backup-<timestamp>.tar.gz
make restore # list available backups
```
To restore manually:
@@ -145,29 +138,20 @@ make start
---
## 8. Updating PIC
## Updating PIC
```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
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
@@ -199,46 +183,29 @@ Then run `make start` again.
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
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
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.
This generates a new admin password and prints it.
### 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
make show-admin-password # print current password
make reset-admin-password # generate a new random password
```