diff --git a/QUICKSTART.md b/QUICKSTART.md index 00143ed..d617262 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -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://: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://: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://: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 `.pic.ngo` subdomain with Let's Encrypt via DNS-01 - - `cloudflare` — Let's Encrypt via Cloudflare DNS-01 + - `pic_ngo` — automatic `.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-.tar.gz`. - -To list available backups: - -```bash -make restore +make backup # archives config/ and data/ into backups/cell-backup-.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://: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://:8081/login`. +Your session expired or you have not logged in. Go to `http://: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 ```