roof
5dab6377bc
Unit Tests / test (push) Failing after 15m59s
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
212 lines
5.0 KiB
Markdown
212 lines
5.0 KiB
Markdown
# Quick Start
|
|
|
|
This guide walks through a first-time PIC installation on a clean Linux host.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- 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
|
|
|
|
The installer handles all software dependencies (git, docker, make, etc.) automatically.
|
|
|
|
---
|
|
|
|
## Option A — One-line installer (recommended)
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
## 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 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.
|
|
|
|
---
|
|
|
|
## Complete the setup wizard
|
|
|
|
The setup wizard appears automatically on first start. All API requests redirect to `/setup` until it is finished.
|
|
|
|
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)
|
|
- `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)
|
|
- **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 cell identity to `config/api/cell_config.json`, and redirects to the login page.
|
|
|
|
---
|
|
|
|
## Log in
|
|
|
|
After the wizard you are redirected to `/login`.
|
|
|
|
- **Username:** `admin`
|
|
- **Password:** the password you set in the wizard
|
|
|
|
---
|
|
|
|
## Add a WireGuard peer
|
|
|
|
Go to **Peers** in the sidebar.
|
|
|
|
1. Click **Add Peer**.
|
|
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 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 traffic can be routed through the cell.
|
|
|
|
---
|
|
|
|
## Day-to-day operations
|
|
|
|
```bash
|
|
# Check container status and API health
|
|
make status
|
|
|
|
# Follow logs from all services
|
|
make logs
|
|
|
|
# Follow logs from a single service
|
|
make logs-api
|
|
make logs-wireguard
|
|
make logs-caddy
|
|
|
|
# Open a shell inside a container
|
|
make shell-api
|
|
make shell-dns
|
|
```
|
|
|
|
---
|
|
|
|
## Backup and restore
|
|
|
|
```bash
|
|
make backup # archives config/ and data/ into backups/cell-backup-<timestamp>.tar.gz
|
|
make restore # list available backups
|
|
```
|
|
|
|
To restore manually:
|
|
|
|
```bash
|
|
tar -xzf backups/cell-backup-YYYYMMDD-HHMMSS.tar.gz
|
|
make start
|
|
```
|
|
|
|
---
|
|
|
|
## Updating PIC
|
|
|
|
```bash
|
|
make update # git pull + rebuild + restart
|
|
```
|
|
|
|
---
|
|
|
|
## Uninstalling
|
|
|
|
```bash
|
|
make uninstall # stops containers; prompts to also delete config/ and data/
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Containers not starting
|
|
|
|
```bash
|
|
make logs
|
|
make logs-api
|
|
```
|
|
|
|
Look for errors about missing config files or port conflicts.
|
|
|
|
### Port 53 already in use
|
|
|
|
On Ubuntu and Debian, `systemd-resolved` listens on port 53. Disable it:
|
|
|
|
```bash
|
|
sudo systemctl disable --now systemd-resolved
|
|
sudo rm /etc/resolv.conf
|
|
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
|
|
```
|
|
|
|
Then run `make start` again.
|
|
|
|
### WireGuard container fails to load the kernel module
|
|
|
|
```bash
|
|
sudo modprobe wireguard
|
|
```
|
|
|
|
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 / UI shows "Not authenticated"
|
|
|
|
Your session expired or you have not logged in. Go to `http://<host-ip>:8081/login`.
|
|
|
|
### API returns 503 "Authentication not configured"
|
|
|
|
The auth file exists but contains no accounts. To recover:
|
|
|
|
```bash
|
|
make reset-admin-password
|
|
```
|
|
|
|
This generates a new admin password and prints it.
|
|
|
|
### Forgot the admin password
|
|
|
|
```bash
|
|
make show-admin-password # print current password
|
|
make reset-admin-password # generate a new random password
|
|
```
|