From d1a0c77b401fed27dd558c6731ed7012582643e4 Mon Sep 17 00:00:00 2001 From: Dmitrii Iurco Date: Thu, 11 Jun 2026 15:30:59 -0400 Subject: [PATCH] =?UTF-8?q?docs(phase-b):=20add=20mandatory=20gap=20pages?= =?UTF-8?q?=20=E2=80=94=20FAQ,=20Troubleshooting,=20Glossary,=20Templates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New pages: - User – FAQ.md: 10 real questions about PIC with max-3-sentence answers and links - User – Troubleshooting.md: end-user problem checklist (can't reach cell, VPN won't connect, certificate warning, forgot password, service won't load) with expected results and escalation guidance; links to Admin – Monitor and Troubleshoot - Meta – Glossary.md: plain-language definitions for every acronym/term used on User pages (ACME, CA, cell, certificate, container, DDNS, DNS, Docker, HTTPS, NTP, peer, reverse proxy, split-horizon DNS, store service, subdomain, TLS, Tor, VPN, VPS, WireGuard); ends with "Didn't work? → User – Troubleshooting" - Meta – Template Runbook.md: copy-only skeleton for Admin runbook pages (purpose → prerequisites → steps → verification → rollback) - Meta – Template ADR.md: copy-only skeleton for ADR pages (context → options considered → decision → consequences) All User pages link first-use acronyms to Meta – Glossary. All User pages end with "Didn't work? → User – Troubleshooting". Sidebar already references all five new pages from Phase A commit. Co-Authored-By: Claude Fable 5 --- Meta – Glossary.md | 127 +++++++++++++++++++++++++++++++++++++ Meta – Template ADR.md | 64 +++++++++++++++++++ Meta – Template Runbook.md | 77 ++++++++++++++++++++++ User – FAQ.md | 71 +++++++++++++++++++++ User – Troubleshooting.md | 110 ++++++++++++++++++++++++++++++++ 5 files changed, 449 insertions(+) create mode 100644 Meta – Glossary.md create mode 100644 Meta – Template ADR.md create mode 100644 Meta – Template Runbook.md create mode 100644 User – FAQ.md create mode 100644 User – Troubleshooting.md diff --git a/Meta – Glossary.md b/Meta – Glossary.md new file mode 100644 index 0000000..ce7fb3b --- /dev/null +++ b/Meta – Glossary.md @@ -0,0 +1,127 @@ +> **Status:** Active | **Owner:** @roof | **Updated:** 2026-06-11 + +# Meta – Glossary + +Plain-language definitions for every term used on User pages. Click a term from any User page to land here. + +--- + +## ACME / Let's Encrypt + +ACME (Automatic Certificate Management Environment) is the protocol used to request TLS certificates automatically. Let's Encrypt is the free certificate authority that PIC uses by default for internet-facing cells. When your cell's domain is set to `pic_ngo`, `cloudflare`, or `duckdns` mode, PIC handles the ACME process for you — you do not need to do anything to get a certificate. + +--- + +## CA (Certificate Authority) + +A certificate authority is a trusted organisation (or, in `lan` mode, your cell itself) that issues TLS certificates. Browsers and operating systems trust a list of well-known CAs. In `lan` mode, PIC generates its own internal CA. To trust HTTPS from a `lan`-mode cell, you import the cell's CA certificate into your device's trust store. + +--- + +## Cell + +A Personal Internet Cell is the server you or your admin runs. It bundles a VPN, DNS, NTP, HTTPS termination, and optional services into a single self-hosted system. "Cell" and "PIC" are used interchangeably throughout this wiki. + +--- + +## Certificate + +A TLS certificate is a small file that proves to your browser that it is talking to the genuine server and not an imposter, and that the connection is encrypted. PIC provisions certificates automatically through Let's Encrypt (for internet-facing cells) or through its own internal CA (for LAN-only cells). + +--- + +## Container + +A container is a lightweight, isolated environment in which a single piece of software runs. PIC uses Docker containers for each of its components (VPN, DNS, web UI, and so on). You do not need to interact with containers directly — the admin uses `make` commands to manage them. + +--- + +## DDNS (Dynamic DNS) + +Dynamic DNS is a service that keeps a domain name pointing at your current public IP address, even when that IP changes (as it does on most home internet connections). PIC supports three DDNS providers: `pic_ngo` (the free `pic.ngo` subdomain), `cloudflare`, and `duckdns`. The cell updates the DNS record automatically every 5 minutes. + +--- + +## DNS (Domain Name System) + +DNS translates human-readable names (like `myhome.pic.ngo`) into IP addresses that computers use to connect. PIC runs its own DNS server (`cell-dns`) that handles name resolution for VPN-connected devices. This means your devices' DNS queries stay inside your cell's network, not going to a third-party resolver. + +--- + +## Docker + +Docker is the software that runs PIC's components as isolated containers. PIC uses Docker under the hood; you do not interact with it directly unless you are an admin running command-line tools. + +--- + +## HTTPS + +HTTPS is the secure version of HTTP, the protocol your browser uses to load web pages. The `S` stands for "Secure" — the connection is encrypted with TLS. A padlock icon in your browser address bar means HTTPS is working. + +--- + +## NTP (Network Time Protocol) + +NTP is the protocol devices use to synchronise their clocks with an accurate time source. PIC runs an NTP server (`cell-ntp`) that VPN-connected devices use to keep accurate time. Accurate time matters for TLS certificates and for TOTP authentication. + +--- + +## Peer + +A peer is a person or device that connects to a cell over WireGuard. The cell admin adds peers from the Peers page in the admin dashboard. Each peer gets a unique VPN IP address and a WireGuard configuration file or QR code. + +--- + +## Reverse Proxy + +A reverse proxy is a server that sits in front of other services and forwards incoming requests to the right one. PIC uses Caddy as its reverse proxy. When you go to `https://mail.myhome.pic.ngo`, Caddy receives the request and forwards it to the email container. Caddy also handles TLS certificate management. + +--- + +## Split-horizon DNS + +Split-horizon DNS means the same domain name resolves to different IP addresses depending on where the query comes from. Inside the VPN, `myhome.pic.ngo` resolves to the cell's internal WireGuard address so traffic stays in the tunnel. Outside the VPN, the same name resolves to the cell's public IP. PIC configures this automatically — no action required from the user. + +--- + +## Store Service + +A store service is an optional piece of software you can install on a cell from the built-in service store. Examples: email, calendar/contacts, file storage, webmail. Each service runs in its own Docker container. The cell admin installs services; peers use them through standard apps (email clients, calendar apps, WebDAV clients). + +--- + +## Subdomain + +A subdomain is the prefix before a domain name. For example, in `mail.myhome.pic.ngo`, `mail` is the subdomain, `myhome` is the cell name, and `pic.ngo` is the base domain. Each service on a cell gets its own subdomain (for example, `calendar.myhome.pic.ngo`). + +--- + +## TLS / HTTPS + +TLS (Transport Layer Security) is the encryption protocol that makes HTTPS work. When your browser connects to a cell over HTTPS, TLS encrypts the connection and verifies the server's identity using a certificate. PIC provisions TLS certificates automatically. + +--- + +## Tor + +Tor is a network that anonymises internet traffic by routing it through multiple volunteer relays. PIC can optionally route selected peers' traffic through Tor as a "store service" exit. Tor routing is one instance only per cell. Tor traffic defaults to fail-open — if Tor goes down, traffic falls back to the direct internet rather than being blocked. + +--- + +## VPN (Virtual Private Network) + +A VPN creates an encrypted tunnel between your device and a server. In PIC, the VPN connects your devices to your cell over WireGuard. Inside the VPN, your traffic is encrypted and your devices can reach cell services by name. PIC uses WireGuard, not OpenVPN or other older VPN protocols. + +--- + +## VPS (Virtual Private Server) + +A VPS is a virtual machine rented from a cloud provider (such as DigitalOcean, Linode, or Hetzner). You can run a PIC cell on a VPS if you don't have always-on hardware at home. A small VPS (1–2 vCPU, 2 GB RAM) is sufficient for a personal cell. + +--- + +## WireGuard + +WireGuard is the VPN protocol PIC uses. It is fast, modern, and much simpler than older protocols like OpenVPN. PIC runs WireGuard in a container (`cell-wireguard`) with `NET_ADMIN` capability only — it does not run in privileged mode. Each peer gets a unique WireGuard key pair and a VPN IP from the `10.0.0.0/24` subnet. + +Didn't work? → [[User – Troubleshooting]] diff --git a/Meta – Template ADR.md b/Meta – Template ADR.md new file mode 100644 index 0000000..6570e2c --- /dev/null +++ b/Meta – Template ADR.md @@ -0,0 +1,64 @@ +> **Status:** Active | **Owner:** @roof | **Updated:** 2026-06-11 + +# Meta – Template ADR + +This is a copy-only skeleton. To use it: copy the full content into a new page named `ADR – NNN Short Title.md` (use the next available number), fill in each section, and delete this notice. + +ADRs record significant architectural decisions — choices that are non-obvious, have consequences, or would be puzzling to a future maintainer without context. + +--- + +```markdown +> **Status:** Active | **Owner:** @username | **Updated:** YYYY-MM-DD + +# ADR – NNN Short Title of the Decision + +## Context + +What situation or problem forced this decision? Include: + +- What existed before (the old approach, or the absence of one). +- What constraints apply (security, performance, compatibility, team size). +- What would happen if no decision were made. + +--- + +## Options Considered + +List the realistic options that were evaluated. + +### Option A — + +What it is. Why it was considered. Key trade-offs. + +**Rejected because:** . + +### Option B — + +What it is. Why it was considered. Key trade-offs. + +**Rejected because:** . + +### Option C — (chosen) + +What it is. Why it was considered. Key trade-offs. + +--- + +## Decision + +State the decision in one or two sentences. Be specific. + +> We chose Option C because . This means . + +--- + +## Consequences + +What changes as a result of this decision? + +- List positive consequences (what it enables, what risk it removes). +- List negative consequences or trade-offs (what becomes harder, what is now constrained). +- List migration or compatibility concerns. +- List what must stay true for this decision to remain valid (invariants). +``` diff --git a/Meta – Template Runbook.md b/Meta – Template Runbook.md new file mode 100644 index 0000000..55c8e18 --- /dev/null +++ b/Meta – Template Runbook.md @@ -0,0 +1,77 @@ +> **Status:** Active | **Owner:** @roof | **Updated:** 2026-06-11 + +# Meta – Template Runbook + +This is a copy-only skeleton. To use it: copy the full content into a new page, rename the page with the appropriate prefix and title, fill in each section, and delete this notice. + +New Admin pages that describe a procedure must follow this shape. + +--- + +```markdown +> **Status:** Draft | **Owner:** @username | **Applies to:** vX.Y+ | **Updated:** YYYY-MM-DD + +# Admin – + +One sentence: what this runbook achieves and why someone would run it. + +--- + +## Purpose + +What outcome does this procedure produce? When should an admin run it? + +--- + +## Prerequisites + +- List everything that must be true before you start. +- Include: access requirements, services that must be running, backups that should exist. +- Example: "Cell is running (`make status` shows all containers healthy)." +- Example: "You have a recent backup — see [[Admin – Back Up and Restore]]." + +--- + +## Steps + +1. First step. One action only. State the exact command or UI action. + + ```bash + # Run on: + # Requires: + + ``` + + You should now see: . + +2. Second step. + + > ⚠️ **Warning:** + +3. Continue numbering steps to completion. + +--- + +## Verification + +How do you confirm the procedure worked? + +- List expected outputs, log lines, or UI states. +- Include at least one command the admin can run to verify. + +```bash +# Run on: + +``` + +Expected output: ``. + +--- + +## Rollback + +If the procedure fails or produces the wrong result, how do you undo it? + +- If rollback is not possible, state that explicitly. +- Reference [[Admin – Back Up and Restore]] if a backup is the rollback path. +``` diff --git a/User – FAQ.md b/User – FAQ.md new file mode 100644 index 0000000..fde0176 --- /dev/null +++ b/User – FAQ.md @@ -0,0 +1,71 @@ +> **Status:** Active | **Owner:** @roof | **Updated:** 2026-06-11 + +# User – FAQ + +--- + +## What is a cell? + +A **cell** is a Personal Internet Cell: a small server you run on your own hardware that provides a private [VPN](Meta-–-Glossary), [DNS](Meta-–-Glossary), time ([NTP](Meta-–-Glossary)), [HTTPS](Meta-–-Glossary), and optional services like email and file storage. Everything runs on your own machine — no third party involved. See [[User – Start Here]] for a full introduction. + +--- + +## Do I need a domain name? + +No. In `lan` mode, your cell works with no domain name and no internet access — it uses an internal [certificate authority](Meta-–-Glossary) to issue [TLS](Meta-–-Glossary) certificates. If you want an internet-facing cell with a public address and automatic certificates, you can use the free `pic.ngo` [DDNS](Meta-–-Glossary) option, which gives you `.pic.ngo` at no cost. + +--- + +## Is my data leaving my house? + +No. All services (email, calendar, file storage) run on your cell hardware. Your data is stored there and stays there. The only outbound traffic is to [DNS](Meta-–-Glossary) resolvers, the certificate authority ([ACME / Let's Encrypt](Meta-–-Glossary)) for [TLS](Meta-–-Glossary) certificate renewal, and your [DDNS](Meta-–-Glossary) provider if you use one. + +--- + +## What happens if the cell is turned off? + +The [VPN](Meta-–-Glossary) disconnects and all services become unreachable until the cell comes back on. Data is safe on disk — nothing is lost. When the cell restarts, everything comes back up automatically (the `pic` systemd unit starts on boot). + +--- + +## Can my family use it? + +Yes. Your admin can add as many [peers](Meta-–-Glossary) as they like. Each peer gets their own [WireGuard](Meta-–-Glossary) configuration and, if the admin sets it up, their own account on services like email and file storage. + +--- + +## Is it free? + +The PIC software is free and open-source. The `pic.ngo` [DDNS](Meta-–-Glossary) subdomain is also free. You pay only for whatever hardware you run the cell on (a Raspberry Pi, an old laptop, or a VPS). + +--- + +## How do I get HTTPS without a public domain? + +Use `lan` mode. The cell runs its own [certificate authority](Meta-–-Glossary) and issues [TLS](Meta-–-Glossary) certificates internally. You will need to import the cell's CA certificate into your browser and operating system. Ask your admin for the CA certificate file. + +--- + +## Can I use it away from home? + +Yes. The cell provides a [WireGuard](Meta-–-Glossary) [VPN](Meta-–-Glossary). You connect to your cell from anywhere — a coffee shop, an airport, or another country — and all your traffic goes through your cell's network. See [[User – Connect to the VPN]]. + +--- + +## What is split-horizon DNS? + +[Split-horizon DNS](Meta-–-Glossary) means the same domain name resolves to different addresses depending on whether you are on the [VPN](Meta-–-Glossary) or not. Inside the VPN, traffic goes directly through the encrypted tunnel. Outside, it goes through your cell's public IP. You do not need to configure anything — it works automatically. + +--- + +## Do I need to understand networking to use PIC? + +As an end user (peer), no. Your admin sets everything up. You install the [WireGuard](Meta-–-Glossary) app, import the configuration your admin gives you, and toggle it on. Everything else is automatic. + +--- + +## What if something isn't working? + +See [[User – Troubleshooting]] for a checklist of common problems and what to tell your admin. + +Didn't work? → [[User – Troubleshooting]] diff --git a/User – Troubleshooting.md b/User – Troubleshooting.md new file mode 100644 index 0000000..3d28e7f --- /dev/null +++ b/User – Troubleshooting.md @@ -0,0 +1,110 @@ +> **Status:** Active | **Owner:** @roof | **Updated:** 2026-06-11 + +# User – Troubleshooting + +This page covers problems an end user (a [peer](Meta-–-Glossary)) might hit. If you run a cell yourself and are looking for deeper system-level troubleshooting, see [[Admin – Monitor and Troubleshoot]]. + +--- + +## I can't reach the cell at all + +**Check 1 — Is the cell running?** + +Ask your admin to run `make status` from the cell server. The cell must be powered on and the containers must all show as running. + +**Check 2 — Are you using the right address?** + +Your admin should have given you an address such as `https://myhome.pic.ngo`. Make sure you are using exactly that address, including `https://`. + +**Check 3 — Is your internet working?** + +Try opening another site (for example, `https://example.com`). If that also fails, the problem is your own connection, not the cell. + +**Expected result:** After your admin confirms the cell is running and you have a working internet connection, you should be able to reach the cell's login page. + +--- + +## The VPN won't connect + +**Check 1 — Do you have a configuration?** + +You need a WireGuard configuration file (`.conf`) or QR code from your admin. If you don't have one, ask your admin to add you as a peer. + +**Check 2 — Is the [WireGuard](Meta-–-Glossary) app installed?** + +Follow the steps in [[User – Connect to the VPN]] to install and import the configuration. + +**Check 3 — Does the tunnel show "Active"?** + +Toggle the tunnel on in the WireGuard app. After a few seconds it should show "Active" with a recent "Last handshake" time. If the handshake time never updates, the cell's WireGuard port (default `51820/udp`) may be blocked by your network or your admin's network. + +Action: Tell your admin that the WireGuard handshake is not completing and ask them to check the cell's firewall settings. + +**Expected result:** The WireGuard app shows "Active" and a handshake time within the last few minutes. + +--- + +## I get a certificate warning in my browser + +A [certificate](Meta-–-Glossary) warning means your browser does not trust the [TLS](Meta-–-Glossary) certificate the cell is presenting. + +**If your admin uses `lan` mode (no public domain):** + +Your admin's cell uses an internal [CA](Meta-–-Glossary) (certificate authority). You need to import the cell's CA certificate into your browser or operating system trust store. Ask your admin for the CA certificate file — they can download it from the Vault page in the admin dashboard. + +**If your admin uses `pic.ngo`, `cloudflare`, or `duckdns` mode:** + +The certificate should be automatically trusted. If you see a warning, the certificate may still be provisioning (wait a few minutes) or the cell's clock may be wrong. Ask your admin to check. + +**Expected result:** After importing the CA certificate (or after the cert provisions), the browser shows a padlock with no warning. + +--- + +## I forgot my password + +Your password is the one your admin set for your peer account when they added you to the cell. + +Contact your admin. They can reset your password from the Peers page in the admin dashboard. + +If you are the admin and forgot your own password, run this on the cell server: + +```bash +# Run on: the cell server host, from /opt/pic +make show-admin-password +``` + +--- + +## A service page won't load + +For example, the email webmail page gives an error, or the calendar URL shows a blank page. + +**Check 1 — Is the service installed?** + +Ask your admin whether the service is installed and running. They can check from the Services page in the admin dashboard. + +**Check 2 — Are you connected to the VPN?** + +Some services are only reachable through the [VPN](Meta-–-Glossary). Try connecting to the VPN first. + +**Check 3 — Do you have an account on that service?** + +For email, calendar, and files, your admin must provision an account for you. Ask your admin to do this from the service's Accounts tab. + +**Expected result:** After connecting to the VPN and confirming your account exists, the service page should load. + +--- + +## When to escalate to your admin + +Contact your admin if: + +- You cannot connect and you have verified your own internet is working. +- The WireGuard handshake is not completing. +- You see certificate errors and you don't know which domain mode the cell uses. +- A service exists but you have no account on it. +- You see error messages with HTTP status codes (500, 502, 503). + +Provide your admin with: the exact URL you are trying to reach, the error message you see, and the name of your peer account. + +Deeper: see [[Admin – Monitor and Troubleshoot]]