diff --git a/docs/home-user-guide.md b/docs/home-user-guide.md new file mode 100644 index 0000000..ce386c1 --- /dev/null +++ b/docs/home-user-guide.md @@ -0,0 +1,337 @@ +# Vigilar Home User Guide + +This guide takes you from a bare mini PC to working cameras on your phone. +It assumes you are comfortable with a Linux command line and can SSH into +a machine on your network. + +If you are running Vigilar on a server you already administer, see the +[Operator Guide](operator-guide.md) instead. + +## What you will end up with + +- A small always-on box in your house that records from your IP cameras. +- A web UI at `http://:49735` on your LAN. +- Push notifications on your phone when motion is detected. +- Optional nightly config + database backup to a NAS share. + +``` + [IP cameras] --RTSP--> [mini PC running Vigilar] --LAN--> [your phone/browser] + | + +-- optional nightly --> [NAS] +``` + +## What you need + +- A mini PC. x86_64, 4 GB RAM minimum, 128 GB SSD minimum. Any modern + Intel NUC, Beelink, MinisForum, or similar will do. +- A USB stick (8 GB or larger) for installing Linux. +- One or more RTSP IP cameras on your LAN. See the + [Camera Hardware Guide](camera-hardware-guide.md) for picks. +- A phone for push notifications. +- Optional: a NAS on your LAN for backups. + +## Step 1 — Install Linux on the mini PC + +Install Debian 12 or Ubuntu Server 24.04 (or later). The official installers +walk you through it. During install: + +- Choose **OpenSSH server** when asked for tasks/components. +- Set a hostname you will remember (e.g. `vigilar`). +- Create a user with `sudo`. + +After install, note the LAN IP (`ip addr` on the box) and confirm you can +SSH in from your laptop. + +Arch Linux works too — the installer supports both `apt` and `pacman` — +but the rest of this guide assumes a Debian/Ubuntu system. + +## Step 2 — Install Vigilar + +SSH into the mini PC, clone the repository, and run the installer: + +```bash +git clone vigilar +cd vigilar +sudo ./scripts/install.sh +``` + +`install.sh` will: + +- Install system packages (`ffmpeg`, `mosquitto`, `python3`, `nut-client`), + create a locked-down `vigilar` system user, and lay out `/opt/vigilar`, + `/var/vigilar`, and `/etc/vigilar` with the right permissions. +- Build a Python virtualenv at `/opt/vigilar/venv`, install the `vigilar` + package into it, generate a 32-byte storage encryption key at + `/etc/vigilar/secrets/storage.key`, and drop a sample config at + `/etc/vigilar/vigilar.toml`. +- Install the `vigilar.service` systemd unit and a Mosquitto config that + binds the internal MQTT broker to localhost only, then restart Mosquitto. + +Review the `[INFO]` and `[OK]` output. Anything marked `[FAIL]` needs +attention before you continue. + +The installer finishes by printing a short list of follow-up scripts it +does **not** run for you. The ones you want now are: + +```bash +sudo ./scripts/gen_vapid_keys.sh +``` + +That generates the VAPID keypair used for phone push notifications. If +you skip it, cameras and the web UI will still work, but phone push +will not. + +The other optional follow-ups are `gen_cert.sh` (TLS certificates for +HTTPS on the LAN) and `setup_nut.sh` (UPS battery monitoring). You can +come back to those later. + +## Step 3 — Edit the config and set a PIN + +The installer drops a sample config at `/etc/vigilar/vigilar.toml`. Open +it in your editor: + +```bash +sudoedit /etc/vigilar/vigilar.toml +``` + +You'll add cameras from the web UI later, so for now you only need to +set two things: the arm/disarm PIN and the web UI password. + +### PIN + +Vigilar stores the arm/disarm PIN as a keyed hash — there is no recovery. +Generate the hash with the CLI: + +```bash +sudo -u vigilar /opt/vigilar/venv/bin/vigilar config set-pin +``` + +Enter a PIN when prompted (twice). The command prints a line like: + +``` +arm_pin_hash = "…:…" +``` + +Copy that line into the `[system]` section of `/etc/vigilar/vigilar.toml`. + +### Web UI password + +Same idea for the password that protects the web UI: + +```bash +sudo -u vigilar /opt/vigilar/venv/bin/vigilar config set-password +``` + +Paste the printed `password_hash = "…"` line into the `[web]` section. + +### Validate + +Before starting the service, make sure the config parses: + +```bash +sudo -u vigilar /opt/vigilar/venv/bin/vigilar config validate +``` + +It should print `Config OK` and a short summary. If it prints +`Config INVALID`, fix the file and try again. + +## Step 4 — Start it up + +```bash +sudo systemctl enable --now vigilar +sudo systemctl status vigilar +``` + +You should see `active (running)`. Now open a browser on any LAN device: + +``` +http://:49735 +``` + +Log in with the password you set in Step 3. The web port is configurable +under `[web] port` in `/etc/vigilar/vigilar.toml` — the default is +`49735`. + +> Screenshot placeholder: `docs/images/first-run-login.png` + +## Step 5 — Add your first camera + +From the web UI, go to **Cameras → Add camera**. You'll need: + +- A name (e.g. "Front door"). +- The camera's RTSP URL — see the + [Camera Hardware Guide](camera-hardware-guide.md) for the format your + brand uses. +- Username and password for the RTSP stream (often separate from the + camera's admin login). + +Click **Test**, then **Save**. The camera appears in the grid. It idles +at 2 FPS and jumps to 30 FPS when motion is detected, with a 5-second +pre-motion ring buffer so you don't lose the run-up to an event. + +> Screenshot placeholder: `docs/images/add-camera.png` + +Repeat for each camera. The multi-camera grid uses HLS so a handful of +streams are comfortable over LAN Wi-Fi; the single-camera view falls +back to MJPEG for lower latency. + +## Step 6 — Phone push notifications + +Vigilar is a Progressive Web App, so your phone installs it straight +from the browser: + +1. Open `http://:49735` in your phone's browser on the + same Wi-Fi. +2. Log in. +3. Use your browser's "Add to Home Screen" option (Safari: share sheet; + Chrome: three-dot menu). +4. Open the installed app from your home screen. +5. When prompted, allow notifications. + +As long as `gen_vapid_keys.sh` was run back in Step 2, you do not need +to configure anything else. The next motion event will push a +notification to your phone. + +**Note on the event timeline:** the in-browser event list does not +update live today — you need to refresh the page to see new events. +Push notifications to your phone work independently and do arrive in +real time. Fixing live timeline updates in the browser is on the +roadmap. + +## Step 7 — Optional: NAS backup + +Vigilar ships a `backup.sh` script that tars the SQLite database and +the contents of `/etc/vigilar` (config + secrets) once a day. It does +**not** back up recordings — those stay on the mini PC's local disk. +Recording backup is planned as a later improvement. + +### Mount the NAS share + +NFS example (swap in SMB if that's what your NAS speaks): + +```bash +sudo apt-get install -y nfs-common +sudo mkdir -p /mnt/nas/vigilar-backups +echo "nas.lan:/volume1/vigilar-backups /mnt/nas/vigilar-backups nfs defaults,_netdev 0 0" | sudo tee -a /etc/fstab +sudo mount -a +``` + +Replace `nas.lan:/volume1/vigilar-backups` with your NAS's actual host +and export path. Confirm it mounted: + +```bash +mount | grep vigilar-backups +``` + +### Schedule `backup.sh` + +Create `/etc/systemd/system/vigilar-backup.service`: + +```ini +[Unit] +Description=Vigilar nightly backup +After=vigilar.service + +[Service] +Type=oneshot +Environment=VIGILAR_BACKUP_DIR=/mnt/nas/vigilar-backups +Environment=VIGILAR_BACKUP_RETENTION_DAYS=30 +ExecStart=/opt/vigilar/scripts/backup.sh +``` + +Create `/etc/systemd/system/vigilar-backup.timer`: + +```ini +[Unit] +Description=Run vigilar backup nightly + +[Timer] +OnCalendar=daily +Persistent=true + +[Install] +WantedBy=timers.target +``` + +Enable the timer: + +```bash +sudo systemctl daemon-reload +sudo systemctl enable --now vigilar-backup.timer +sudo systemctl list-timers | grep vigilar +``` + +Test it immediately without waiting for midnight: + +```bash +sudo systemctl start vigilar-backup.service +ls -lh /mnt/nas/vigilar-backups/ +``` + +You should see a `vigilar-backup-.tar.gz` file. Thirty days +of these will rotate automatically thanks to +`VIGILAR_BACKUP_RETENTION_DAYS`. + +## Troubleshooting + +### The web UI will not load + +- `sudo systemctl status vigilar` — is it running? +- `journalctl -u vigilar -e` — what does the last error say? +- Port 49735 blocked or bound elsewhere? + `sudo ss -tlnp | grep 49735`. +- Wrong address? On the mini PC, `ip addr` shows its LAN IP. + +### A camera will not connect + +- Try the RTSP URL in VLC from your laptop (Media → Open Network + Stream). If VLC cannot play it either, it is a camera or network + problem, not Vigilar. +- Double-check credentials — many cameras have a separate RTSP login + distinct from the admin web login. +- Some cameras need a specific stream path (e.g. `/stream1`, + `/cam/realmonitor?channel=1`). See the + [Camera Hardware Guide](camera-hardware-guide.md). + +### No push notifications on my phone + +- Did you run `sudo ./scripts/gen_vapid_keys.sh`? `install.sh` does + not do this for you. +- Open the PWA from your home screen, not a browser tab. iOS in + particular only delivers web push to installed PWAs. +- Check the browser's notification permission for the site. +- Remember: the in-browser event timeline is not live. Refresh the + page to see events land. Push is the real-time channel. + +### Service keeps restarting + +- `journalctl -u vigilar -n 100` and look at the last stack trace. +- Common cause: invalid `vigilar.toml`. Validate it: + ```bash + sudo -u vigilar /opt/vigilar/venv/bin/vigilar config validate + ``` +- The supervisor will give up after ten consecutive restarts of the + same subsystem, so a persistent crash loop eventually stops on its + own — check the logs and fix the underlying cause. + +### I forgot my PIN + +There is no recovery — the PIN is only stored as a hash. Generate a new +one and replace the line in `/etc/vigilar/vigilar.toml`: + +```bash +sudo -u vigilar /opt/vigilar/venv/bin/vigilar config set-pin +sudoedit /etc/vigilar/vigilar.toml # replace arm_pin_hash in [system] +sudo systemctl restart vigilar +``` + +The same trick works for a forgotten web UI password — use +`config set-password` instead and update `password_hash` in `[web]`. + +## Where to go next + +- [Operator Guide](operator-guide.md) — configuration reference, backups, upgrades, security. +- [Camera Hardware Guide](camera-hardware-guide.md) — buying advice and + RTSP URL formats per brand. +- [Architecture Overview](architecture/overview.md) — how Vigilar is put + together under the hood.