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 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 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:

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:

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:

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:

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:

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:

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

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 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):

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:

mount | grep vigilar-backups

Schedule backup.sh

Create /etc/systemd/system/vigilar-backup.service:

[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:

[Unit]
Description=Run vigilar backup nightly

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Enable the timer:

sudo systemctl daemon-reload
sudo systemctl enable --now vigilar-backup.timer
sudo systemctl list-timers | grep vigilar

Test it immediately without waiting for midnight:

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.

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:

  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:

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 — configuration reference, backups, upgrades, security.
• Camera Hardware Guide — buying advice and RTSP URL formats per brand.
• Architecture Overview — how Vigilar is put together under the hood.