Installation & Setup

This guide walks through a complete, beginner-friendly setup of Viewu.

If you are unsure which remote access model to use, start with Tailscale (VPN) first. You can always move to Cloudflare later once everything works locally.

Quick start (pick the path that matches your setup)

Quick start A: Local-only (no notifications)

Use this if you want to confirm the app works before adding any server infrastructure.

1. In Viewu: Settings → NVR
2. Set your Frigate URL (example):
   • http://192.168.1.152:5000
3. Tap Test / Connect (or navigate back and confirm the status changes)
4. Open the Timeline and confirm you see events
5. Open a camera and confirm live playback

If you can browse the timeline and view a camera, your core NVR connection is correct.

Quick start B: Notifications (MQTT + Viewu Server)

Use this once Quick start A is working.

1. Get MQTT working first:
   • Mosquitto (MQTT)
2. Deploy Viewu Server:
   • Viewu Server → Docker Setup
3. In Viewu: configure Settings → MQTT
4. In Viewu: Settings → Notifications / Pairing → Pair
5. Trigger a Frigate event and confirm:
   • Viewu Server logs show the event
   • Your phone receives a push notification

Quick start C: Remote access without VPN (Cloudflare Tunnel + Access)

Use this if you want remote access without requiring Tailscale to be connected.

1. Create a Cloudflare Tunnel that routes:
   • nvr.example.com → http://127.0.0.1:5000
   • (optional) mqtt.example.com → http://127.0.0.1:9001 (WebSockets)
2. Protect both hostnames with Cloudflare Access (recommended)
3. In Viewu: set NVR URL to https://nvr.example.com
4. In Viewu: paste Cloudflare Access Service Token headers (Client ID + Secret)
5. Verify with curl before debugging the app:
   • Cloudflare Tunnels

Step 0: Know what you are building

There are two different “levels” of setup:

1. App-only setup (no push notifications)
   • View live cameras
   • Browse events in the timeline
2. App + Server setup (push notifications)
   • Requires: MQTT broker + Viewu Server + pairing

If you only want local viewing, do Step 1 and Step 2 and stop.

Step 1: Configure your Frigate (NVR) connection

Open Viewu → Settings → NVR. (Below port 5000 is mapped to 5555)

1.1 Choose the best URL form

Recommended (best overall): hostname + HTTPS

• Example: https://nvr.example.com
• Why: trusted certificates and hostnames reduce iOS TLS friction.

LAN / VPN-only: IP + HTTP

• Example: http://192.168.1.152:5000
• Why: fast and simple on a home LAN.
• Note: self-signed HTTPS on an IP can be problematic for some iOS playback paths.

Common trap: If you use https://192.168.x.x with a self-signed certificate, the web UI might load in a browser, but iOS media/snapshot fetching can still fail. When in doubt, start with plain HTTP on LAN, then upgrade to trusted HTTPS once the basics work.

1.2 Verify the URL before you blame the app

From a device on the same network as your phone (Mac/PC), run:

curl -sS https://nvr.example.com/api/version

If that returns version information, your base URL is correct.

If you are using an IP:

curl -sS http://192.168.1.152:5000/api/version

1.3 If you use Cloudflare Access (Service Token)

If your nvr.example.com is protected by Cloudflare Access, the app must send:

• CF-Access-Client-Id
• CF-Access-Client-Secret

These come from a Cloudflare Service Token (not a user login flow).

In Viewu: Settings → NVR → Cloudflare/Headers
Paste the Client ID and Client Secret exactly.

Tip: If your logs show the Client Secret is “missing” or length is 0, re-enter it and save. When debugging, check Viewu logs to confirm the app is sending both headers.

1.4 Frigate auth on 8971 (if you use it)

If your Frigate stack uses port 8971 (common for auth-enabled setups), Viewu supports that as well. The key is that the base URL must match the port you actually use. Consult the Frigate documents to find your key.

Step 2: Choose remote access (VPN vs Cloudflare)

Option A: Tailscale (recommended starting point)

Use this when you only want your own devices to access your NVR.

1. Install Tailscale on your NVR server (or a machine that can reach it).
2. Install Tailscale on your iPhone.
3. In Viewu, use the Tailscale IP for Frigate (example: http://100.x.y.z:5000).

Important: if you want remote timeline access while away from home, your phone must be connected to Tailscale.

Guide: Notifications → Tailscale (VPN)

Option B: Cloudflare Tunnel

Use this when you want access without requiring the VPN to be connected.

1. Create a Cloudflare Tunnel.
2. Route nvr.example.com to your Frigate (or Nginx proxy).
3. (Recommended) Protect it with Cloudflare Access.
4. In Viewu, set your NVR URL to https://nvr.example.com.

Guide: Notifications → Cloudflare Tunnels

Step 3: Configure MQTT (only if you want push notifications)

Open Viewu → Settings → MQTT.

3.1 Typical LAN MQTT (Mosquitto)

• Host: your broker IP (e.g., 192.168.1.100)
• Port: 1883
• Username/Password: your Mosquitto credentials

What “success” looks like:

• Viewu Server logs show it can connect to the broker
• Triggering a Frigate event produces MQTT messages

3.2 Cloudflare Tunnel MQTT (WebSockets)

If your MQTT broker is behind Cloudflare Tunnel, you will almost always use MQTT over WebSockets:

• Host: mqtt.example.com
• Scheme: wss
• Origin service: must be HTTP websockets on the broker (commonly port 9001)
• If protected by Cloudflare Access, set the same CF-Access-Client-Id/Secret headers

Common trap: The most frequent MQTT failure with Cloudflare is using a TCP tunnel or pointing the origin to https://.... For MQTT websockets you typically want Cloudflare forwarding to http://127.0.0.1:9001 on the origin.

Step 4: Pair with Viewu Server (push notifications)

1. Deploy Viewu Server: Viewu Server → Docker Setup
2. In Viewu, open Settings → Notifications / Pairing
3. Tap Pair
4. Confirm it shows:
   • Enabled
   • A server version
   • A device identifier registered on the server

If pairing works but notifications do not, skip to Step 5 and validate the end-to-end chain in order.

Step 5: Basic troubleshooting checklist (in the right order)

When something fails, validate in this sequence. It saves a lot of time.

1. NVR URL works
   • Can you curl /api/version from your laptop on the same network?
2. Cloudflare Access is correct (if enabled)
   • Does the request succeed when you send the Access headers?
3. MQTT is producing events
   • Can you see messages with mosquitto_sub on the broker?
4. Viewu Server can subscribe
   • Do server logs show it connects and receives messages?
5. Phone can fetch snapshots (for rich notifications)
   • If your phone is off-LAN, can it reach the snapshot URL at notification time?

Useful commands:

docker logs -f viewu