vigilar/docs/home-user-guide.md

# 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://<mini-pc-ip>: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 <repo URL> 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://<mini-pc-ip>: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://<mini-pc-ip>: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-<timestamp>.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.