# 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
```