pic/QUICKSTART.md

Quick Start

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)
• 2 GB+ RAM, 10 GB+ disk
• Ports 53, 80, 443, 51820/udp, 25, 587, 993 available on the host

Verify the WireGuard module is available:

sudo modprobe wireguard

---

1. Clone the repository

git clone gitea@192.168.31.50:roof/pic.git pic
cd pic

---

2. Start the stack

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:

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:

• 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.
• 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
  • 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.

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.

---

4. Log in

After the wizard, you are redirected to the login page at /login.

Log in with:

• Username: admin
• Password: the password you set in the wizard

---

5. 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 all traffic can be routed through the cell.

---

6. Day-to-day operations

# 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

---

7. Backup

Before making significant changes, create a backup:

make backup

This archives config/ and data/ into backups/cell-backup-<timestamp>.tar.gz.

To list available backups:

make restore

To restore manually:

tar -xzf backups/cell-backup-YYYYMMDD-HHMMSS.tar.gz
make start

---

8. Updating PIC

make update

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

make uninstall

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

Containers not starting

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:

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

sudo modprobe wireguard

On minimal installs you may need to install wireguard-tools and the kernel headers for the running kernel before modprobe succeeds.

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"

Your session has expired or you have not logged in yet. Go to http://<host-ip>:8081/login.

API returns 503 with "Authentication not configured"

The users file exists but contains no accounts. This should not happen after a normal wizard completion. To recover:

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:

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

make show-admin-password

If that doesn't help (e.g. the setup data file is missing):

make reset-admin-password