> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nightjar.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosting FAQ

> Hardware sizing, disk math, and troubleshooting for self-hosted nodes.

## Hardware sizing

Recording is a stream copy (no transcoding) and object detection runs only on motion snapshots, so Nightjar is lighter than transcoding NVRs. Rough guidance:

| Hardware                        | Comfortable load                                                   |
| ------------------------------- | ------------------------------------------------------------------ |
| Raspberry Pi 5 (arm64)          | 2–4 cameras with motion + AI detection, if cameras have substreams |
| NUC / used mini-PC (recent x86) | 6+ cameras with headroom                                           |
| NAS with Docker                 | Depends on CPU — treat like the closest class above                |

The main CPU costs are motion decoding (5 fps per camera, cheap on a substream, expensive on a 4K main stream) and the occasional YOLOX-tiny inference. Configure substreams — on small hardware it is the difference between comfortable and struggling.

## Disk sizing

Continuous 1080p H.264 recording runs roughly **1–2 GB per hour per camera** depending on bitrate; 2K/4K cameras more. Quick math for the default 14-day retention:

| Cameras   | Per day (mid estimate) | 14 days  |
| --------- | ---------------------- | -------- |
| 1 × 1080p | \~35 GB                | \~0.5 TB |
| 3 × 1080p | \~105 GB               | \~1.5 TB |
| 3 × 2K/4K | \~200+ GB              | \~3+ TB  |

If the disk fills before `maxDays`, the [disk watermark](/guides/recording-and-events#retention) (default 90%) prunes oldest footage first — the node degrades retention, never crashes the disk. Undersize the disk and you simply keep fewer days.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Camera won't connect">
    Test the RTSP URL from the node's host before blaming Nightjar:

    ```bash theme={null}
    ffprobe -rtsp_transport tcp "rtsp://user:pass@192.168.1.50:554/h264Preview_01_main"
    ```

    Or open the URL in VLC (Media → Open Network Stream). If those fail, the URL, credentials, or camera network settings are wrong — check the [brand patterns](/guides/cameras). Special characters in passwords must be URL-encoded (`@` → `%40`). Also confirm RTSP is enabled in the camera's own settings, and use `POST /api/cameras/{id}/probe` to see the node's view of the stream.
  </Accordion>

  <Accordion title="No motion events">
    Check, in order: the camera's `detect` flag is `true`; a substream URL is configured (or the main stream is decodable); and the motion actually crosses the trigger — more than 1.5% of the frame changing for 2 consecutive frames at 5 fps. Distant or tiny motion in a wide shot can stay under the threshold. Set `LOG_LEVEL=debug` and watch the logs for the motion decoder starting and for `motion started` lines.
  </Accordion>

  <Accordion title="Events fire but stay kind 'motion'">
    Object detection needs the model file. In Docker it is baked into the image; in local dev you must run `pnpm --filter @nightjar/node fetch-model` once. If the model is missing the node logs a clear hint and detections are disabled — everything else keeps working. Also note detection only upgrades events when it scores ≥ 0.5 on the snapshot.
  </Accordion>

  <Accordion title="Reading container logs">
    ```bash theme={null}
    docker compose logs -f node      # the Nightjar service
    docker compose logs -f go2rtc    # streaming layer
    ```

    The go2rtc admin UI at `http://<host>:1984` shows per-stream status and lets you test playback directly.
  </Accordion>

  <Accordion title="Remote live view won't connect">
    Confirm the node shows cloud state `online` in `GET /api/status`. If the node runs under Docker Desktop on macOS/Windows, WebRTC is degraded by design — use a Linux host. Some strict networks need a TURN relay; see [Remote access](/guides/remote-access#how-remote-live-view-works).
  </Accordion>
</AccordionGroup>

Still stuck? Open an issue at [github.com/Snapsonic/nightjar/issues](https://github.com/Snapsonic/nightjar/issues) with the relevant `docker compose logs` output.