Initial commit: Vigilar DIY home security system

Phase 1 (Foundation): project skeleton, TOML config + Pydantic validation,
MQTT bus wrapper, SQLite schema (9 tables), Click CLI, process supervisor.

Phase 2 (Camera): RTSP capture via OpenCV, MOG2 motion detection with
configurable sensitivity/zones, adaptive FPS recording (2fps idle/30fps
motion) via FFmpeg subprocess, HLS live streaming, pre-motion ring buffer.

Phase 3 (Web UI): Flask + Bootstrap 5 dark theme, 6 blueprints, Jinja2
templates (dashboard, kiosk 2x2 grid, events, sensors, recordings, settings),
PWA with service worker + Web Push, full admin settings UI with config
persistence.

Remote Access: WireGuard tunnel configs, nginx reverse proxy with HLS
caching + rate limiting, bandwidth-optimized remote HLS stream (426x240
@ 500kbps), DO droplet setup script, certbot TLS.

29 tests passing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Aaron D. Lee
2026-04-02 23:11:27 -04:00
commit 845a85d618
69 changed files with 7061 additions and 0 deletions

165
remote/nginx/vigilar.conf Normal file
View File

@@ -0,0 +1,165 @@
# Nginx reverse proxy config for Digital Ocean droplet
# Proxies HTTPS traffic to Vigilar at home via WireGuard tunnel
#
# Install: cp vigilar.conf /etc/nginx/sites-available/vigilar
# ln -s /etc/nginx/sites-available/vigilar /etc/nginx/sites-enabled/
# nginx -t && systemctl reload nginx
#
# TLS: certbot --nginx -d vigilar.yourdomain.com
# Rate limiting zones
limit_req_zone $binary_remote_addr zone=api:10m rate=30r/s;
limit_req_zone $binary_remote_addr zone=stream:10m rate=5r/s;
limit_conn_zone $binary_remote_addr zone=connlimit:10m;
# HLS segment cache — reduces repeat requests hitting the home uplink
proxy_cache_path /var/cache/nginx/vigilar_hls
levels=1:2
keys_zone=hls_cache:10m
max_size=256m
inactive=30s
use_temp_path=off;
# Upstream: Vigilar on home server via WireGuard tunnel
upstream vigilar_home {
server 10.99.0.2:49735;
# If home server goes down, fail fast
keepalive 4;
}
# Redirect HTTP → HTTPS
server {
listen 80;
server_name vigilar.yourdomain.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name vigilar.yourdomain.com;
# TLS (managed by certbot)
ssl_certificate /etc/letsencrypt/live/vigilar.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/vigilar.yourdomain.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
# Security headers
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
add_header X-Frame-Options DENY always;
add_header X-Content-Type-Options nosniff always;
add_header Referrer-Policy strict-origin-when-cross-origin always;
# Connection limits — protect 22 Mbps home uplink
# Max 10 simultaneous connections per IP
limit_conn connlimit 10;
# --- HLS streams (bandwidth-critical path) ---
# Cache .ts segments on the droplet to avoid re-fetching from home
# when multiple remote viewers request the same segment
location ~ ^/cameras/.+/hls/.+\.ts$ {
proxy_pass http://vigilar_home;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Cache segments for 10s — they're 2s segments, so this covers
# multiple viewers watching the same feed without re-fetching
proxy_cache hls_cache;
proxy_cache_valid 200 10s;
proxy_cache_key $uri;
add_header X-Cache-Status $upstream_cache_status;
# Rate limit: 5 segment requests/sec per IP
limit_req zone=stream burst=20 nodelay;
}
# HLS playlists — don't cache (they update every segment)
location ~ ^/cameras/.+/hls/.+\.m3u8$ {
proxy_pass http://vigilar_home;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# No cache — playlists must be fresh
proxy_cache off;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# --- SSE event stream ---
location /events/stream {
proxy_pass http://vigilar_home;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# SSE: disable buffering, long timeout
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
chunked_transfer_encoding on;
proxy_set_header Connection '';
proxy_http_version 1.1;
}
# --- API endpoints ---
location ~ ^/system/api/ {
proxy_pass http://vigilar_home;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
limit_req zone=api burst=10 nodelay;
}
# --- Static assets (cache aggressively on droplet) ---
location /static/ {
proxy_pass http://vigilar_home;
proxy_set_header Host $host;
proxy_cache hls_cache;
proxy_cache_valid 200 1h;
add_header X-Cache-Status $upstream_cache_status;
}
# --- Service worker (must not be cached stale) ---
location = /static/sw.js {
proxy_pass http://vigilar_home;
proxy_set_header Host $host;
proxy_cache off;
add_header Cache-Control "no-cache";
}
# --- Everything else (pages, PWA manifest, etc.) ---
location / {
proxy_pass http://vigilar_home;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
limit_req zone=api burst=20 nodelay;
}
# Deny access to config/sensitive paths
location ~ ^/(config|migrations|scripts|tests) {
deny all;
}
# Max upload size (for config changes, etc.)
client_max_body_size 1m;
# Logging
access_log /var/log/nginx/vigilar_access.log;
error_log /var/log/nginx/vigilar_error.log;
}

187
remote/setup_droplet.sh Executable file
View File

@@ -0,0 +1,187 @@
#!/usr/bin/env bash
# Full setup script for Digital Ocean droplet as Vigilar reverse proxy
# Run this on a fresh Ubuntu 24.04 LTS droplet.
#
# What it does:
# 1. Installs WireGuard, nginx, certbot
# 2. Configures WireGuard tunnel (interactive key exchange)
# 3. Deploys nginx reverse proxy config
# 4. Sets up TLS with Let's Encrypt
# 5. Configures firewall
set -euo pipefail
echo "============================================"
echo " Vigilar — Droplet Reverse Proxy Setup"
echo "============================================"
echo ""
# Require root
if [[ $EUID -ne 0 ]]; then
echo "Run as root: sudo bash setup_droplet.sh"
exit 1
fi
# --- Step 1: Install packages ---
echo "[1/6] Installing packages..."
apt update
apt install -y wireguard nginx certbot python3-certbot-nginx ufw
# --- Step 2: WireGuard ---
echo ""
echo "[2/6] Setting up WireGuard..."
if [[ -f /etc/wireguard/wg0.conf ]]; then
echo " WireGuard already configured. Skipping."
else
# Generate keys
PRIV_KEY=$(wg genkey)
PUB_KEY=$(echo "$PRIV_KEY" | wg pubkey)
echo ""
echo " Droplet PUBLIC key (give this to your home server):"
echo " $PUB_KEY"
echo ""
read -p " Enter home server's PUBLIC key: " HOME_PUB_KEY
cat > /etc/wireguard/wg0.conf <<EOF
[Interface]
Address = 10.99.0.1/32
ListenPort = 51820
PrivateKey = $PRIV_KEY
[Peer]
PublicKey = $HOME_PUB_KEY
AllowedIPs = 10.99.0.2/32
EOF
chmod 600 /etc/wireguard/wg0.conf
systemctl enable --now wg-quick@wg0
echo " WireGuard started. Tunnel IP: 10.99.0.1"
fi
# --- Step 3: Firewall ---
echo ""
echo "[3/6] Configuring firewall..."
ufw --force reset
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp # SSH
ufw allow 80/tcp # HTTP (certbot + redirect)
ufw allow 443/tcp # HTTPS
ufw allow 51820/udp # WireGuard
ufw --force enable
echo " Firewall configured."
# --- Step 4: Nginx ---
echo ""
echo "[4/6] Configuring nginx..."
read -p " Enter your domain (e.g., vigilar.yourdomain.com): " DOMAIN
# Create cache directory
mkdir -p /var/cache/nginx/vigilar_hls
# Deploy config
NGINX_CONF="/etc/nginx/sites-available/vigilar"
if [[ -f "$NGINX_CONF" ]]; then
cp "$NGINX_CONF" "${NGINX_CONF}.bak.$(date +%s)"
fi
# Copy template and replace domain
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
if [[ -f "$SCRIPT_DIR/nginx/vigilar.conf" ]]; then
sed "s/vigilar.yourdomain.com/$DOMAIN/g" "$SCRIPT_DIR/nginx/vigilar.conf" > "$NGINX_CONF"
else
echo " ERROR: nginx/vigilar.conf not found in $SCRIPT_DIR"
echo " Copy it manually to /etc/nginx/sites-available/vigilar"
exit 1
fi
# Enable site
ln -sf "$NGINX_CONF" /etc/nginx/sites-enabled/vigilar
rm -f /etc/nginx/sites-enabled/default
# Test config (will fail on TLS certs — that's OK, certbot fixes it)
echo " Testing nginx config (cert errors expected before certbot)..."
nginx -t 2>/dev/null || true
# --- Step 5: TLS with Let's Encrypt ---
echo ""
echo "[5/6] Setting up TLS..."
echo " Running certbot for $DOMAIN"
echo " Note: DNS must already point $DOMAIN to this droplet's IP."
echo ""
# Temporarily remove SSL directives so nginx starts
# Create a minimal config for certbot
cat > /etc/nginx/sites-available/vigilar-temp <<EOF
server {
listen 80;
server_name $DOMAIN;
location / {
proxy_pass http://10.99.0.2:49735;
}
}
EOF
ln -sf /etc/nginx/sites-available/vigilar-temp /etc/nginx/sites-enabled/vigilar-temp
rm -f /etc/nginx/sites-enabled/vigilar
nginx -t && systemctl reload nginx
# Run certbot
certbot --nginx -d "$DOMAIN" --non-interactive --agree-tos --register-unsafely-without-email || {
echo ""
echo " Certbot failed. Make sure DNS for $DOMAIN points to this server."
echo " You can retry manually: certbot --nginx -d $DOMAIN"
}
# Remove temp config, restore full config
rm -f /etc/nginx/sites-enabled/vigilar-temp /etc/nginx/sites-available/vigilar-temp
ln -sf "$NGINX_CONF" /etc/nginx/sites-enabled/vigilar
# Update the config with certbot's cert paths
sed -i "s|ssl_certificate .*|ssl_certificate /etc/letsencrypt/live/$DOMAIN/fullchain.pem;|" "$NGINX_CONF"
sed -i "s|ssl_certificate_key .*|ssl_certificate_key /etc/letsencrypt/live/$DOMAIN/privkey.pem;|" "$NGINX_CONF"
nginx -t && systemctl reload nginx
# --- Step 6: Verify ---
echo ""
echo "[6/6] Verifying setup..."
echo ""
# Check WireGuard
if wg show wg0 &>/dev/null; then
echo " [OK] WireGuard interface wg0 is up"
else
echo " [!!] WireGuard not running"
fi
# Check nginx
if systemctl is-active --quiet nginx; then
echo " [OK] nginx is running"
else
echo " [!!] nginx is not running"
fi
# Check cert
if [[ -f "/etc/letsencrypt/live/$DOMAIN/fullchain.pem" ]]; then
echo " [OK] TLS certificate present"
else
echo " [!!] TLS certificate missing — run certbot manually"
fi
echo ""
echo "============================================"
echo " Setup complete!"
echo ""
echo " Droplet WireGuard IP: 10.99.0.1"
echo " Home server should be: 10.99.0.2"
echo " Web URL: https://$DOMAIN"
echo ""
echo " Next steps:"
echo " 1. Configure WireGuard on your home server"
echo " 2. Test: ping 10.99.0.2 (from this droplet)"
echo " 3. Start Vigilar on home server"
echo " 4. Access https://$DOMAIN"
echo "============================================"

View File

@@ -0,0 +1,121 @@
#!/usr/bin/env bash
# WireGuard key generation and setup helper
# Run this on BOTH the home server and the droplet to generate keys.
# Then copy the public keys into the appropriate config files.
set -euo pipefail
echo "=== Vigilar WireGuard Setup ==="
echo ""
# Check if WireGuard is installed
if ! command -v wg &>/dev/null; then
echo "Installing WireGuard..."
if command -v apt &>/dev/null; then
sudo apt update && sudo apt install -y wireguard
elif command -v pacman &>/dev/null; then
sudo pacman -S --noconfirm wireguard-tools
else
echo "ERROR: Install WireGuard manually for your OS"
exit 1
fi
fi
echo "Generating WireGuard keys..."
PRIV_KEY=$(wg genkey)
PUB_KEY=$(echo "$PRIV_KEY" | wg pubkey)
echo ""
echo "Private Key: $PRIV_KEY"
echo "Public Key: $PUB_KEY"
echo ""
echo "Save the private key in /etc/wireguard/ and share the PUBLIC key"
echo "with the other end of the tunnel."
echo ""
# Detect if this is the home server or droplet
read -p "Is this the (h)ome server or (d)roplet? [h/d]: " ROLE
if [[ "$ROLE" == "d" ]]; then
echo ""
echo "=== DROPLET SETUP ==="
echo ""
# Save keys
sudo mkdir -p /etc/wireguard
echo "$PRIV_KEY" | sudo tee /etc/wireguard/droplet_private.key > /dev/null
echo "$PUB_KEY" | sudo tee /etc/wireguard/droplet_public.key > /dev/null
sudo chmod 600 /etc/wireguard/droplet_private.key
read -p "Home server's PUBLIC key: " HOME_PUB_KEY
# Generate config
sudo tee /etc/wireguard/wg0.conf > /dev/null <<EOF
[Interface]
Address = 10.99.0.1/32
ListenPort = 51820
PrivateKey = $PRIV_KEY
[Peer]
PublicKey = $HOME_PUB_KEY
AllowedIPs = 10.99.0.2/32
EOF
sudo chmod 600 /etc/wireguard/wg0.conf
# Open firewall
if command -v ufw &>/dev/null; then
sudo ufw allow 51820/udp
sudo ufw allow 443/tcp
sudo ufw allow 80/tcp
echo "Firewall rules added (51820/udp, 80/tcp, 443/tcp)"
fi
# Enable and start
sudo systemctl enable --now wg-quick@wg0
echo ""
echo "WireGuard started on droplet."
echo "Droplet tunnel IP: 10.99.0.1"
echo ""
echo "Share this public key with your home server: $PUB_KEY"
elif [[ "$ROLE" == "h" ]]; then
echo ""
echo "=== HOME SERVER SETUP ==="
echo ""
# Save keys
sudo mkdir -p /etc/wireguard
echo "$PRIV_KEY" | sudo tee /etc/wireguard/home_private.key > /dev/null
echo "$PUB_KEY" | sudo tee /etc/wireguard/home_public.key > /dev/null
sudo chmod 600 /etc/wireguard/home_private.key
read -p "Droplet's PUBLIC key: " DROPLET_PUB_KEY
read -p "Droplet's public IP address: " DROPLET_IP
# Generate config
sudo tee /etc/wireguard/wg0.conf > /dev/null <<EOF
[Interface]
Address = 10.99.0.2/32
PrivateKey = $PRIV_KEY
[Peer]
PublicKey = $DROPLET_PUB_KEY
AllowedIPs = 10.99.0.1/32
Endpoint = ${DROPLET_IP}:51820
PersistentKeepalive = 25
EOF
sudo chmod 600 /etc/wireguard/wg0.conf
# Enable and start
sudo systemctl enable --now wg-quick@wg0
echo ""
echo "WireGuard started on home server."
echo "Home tunnel IP: 10.99.0.2"
echo ""
echo "Share this public key with your droplet: $PUB_KEY"
fi
echo ""
echo "Test connectivity with: ping 10.99.0.1 (from home) or ping 10.99.0.2 (from droplet)"

View File

@@ -0,0 +1,18 @@
# WireGuard config for DIGITAL OCEAN DROPLET (reverse proxy)
# Install: cp wg0-droplet.conf /etc/wireguard/wg0.conf
# Start: systemctl enable --now wg-quick@wg0
[Interface]
# Droplet's WireGuard IP on the tunnel
Address = 10.99.0.1/32
ListenPort = 51820
# Generate with: wg genkey | tee /etc/wireguard/droplet_private.key | wg pubkey > /etc/wireguard/droplet_public.key
PrivateKey = <DROPLET_PRIVATE_KEY>
[Peer]
# Home server
PublicKey = <HOME_PUBLIC_KEY>
# Home server's tunnel IP — traffic to this IP goes through WireGuard
AllowedIPs = 10.99.0.2/32
# No Endpoint needed — home server initiates the connection (NAT traversal)
# No PersistentKeepalive needed — home server sends keepalives

View File

@@ -0,0 +1,21 @@
# WireGuard config for HOME SERVER (Vigilar host)
# Install: cp wg0-home.conf /etc/wireguard/wg0.conf
# Start: systemctl enable --now wg-quick@wg0
[Interface]
# Home server's WireGuard IP on the tunnel
Address = 10.99.0.2/32
# Generate with: wg genkey | tee /etc/wireguard/home_private.key | wg pubkey > /etc/wireguard/home_public.key
PrivateKey = <HOME_PRIVATE_KEY>
# Keep the tunnel alive through NAT (home router)
# Send keepalive every 25s so the NAT mapping doesn't expire
[Peer]
# Digital Ocean droplet
PublicKey = <DROPLET_PUBLIC_KEY>
# Route all tunnel traffic to the droplet
AllowedIPs = 10.99.0.1/32
# Droplet's public IP + WireGuard port
Endpoint = <DROPLET_PUBLIC_IP>:51820
# Critical: keeps tunnel alive through home router NAT
PersistentKeepalive = 25