docs: add home user setup guide
Linear walkthrough from bare mini PC to working cameras on phone, with optional NAS backup. Verified against real install.sh, backup.sh, and CLI subcommands; honest about the in-browser event timeline not being wired to SSE yet (push notifications do work). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
adlee-was-taken
337
docs/home-user-guide.md
Normal file
337
docs/home-user-guide.md
Normal file
@@ -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://<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.
|
||||||
Reference in New Issue
Block a user