Enhancement: Add PUID/PGID support (Still

[TCS-UK]

UPDATED:

Add PUID/PGID support for running Frigate as a non-root user

Problem

Users who run Frigate on NAS devices, Unraid, or any shared host care about
which uid/gid owns the files created inside their mounted volumes (/config,
/media, recordings, etc.). Currently Frigate always runs as root inside the
container, so every recorded clip and database file ends up owned by root on
the host — requiring chmod 777 hacks or making files inaccessible to the host
user.

The two obvious workarounds both fail:

• user: "1000:1000" in Compose — breaks startup entirely. s6-overlay's
  log-prepare runs as that uid and cannot chown /dev/shm/logs/* nobody:nogroup,
  stalling all services before any app process starts.
• PUID/PGID env vars — silently ignored; Frigate has no such mechanism.

Solution

Adds opt-in PUID/PGID support using the same pattern as LinuxServer.io
images, which the self-hosted community already understands well.

How it works

A new user-setup s6-rc oneshot service runs as root immediately after the
base bundle — before prepare or log-prepare — and exits. It:

1. Adjusts the pre-created frigate group to match PGID via groupmod
2. Adjusts the pre-created frigate user to match PUID via usermod
3. Propagates any Docker-injected supplementary groups (e.g. video, render,
   coral from group_add: in Compose) to the frigate user, so that ffmpeg
   processes spawned by both Frigate and go2rtc retain device access
4. chowns /config, /media, /tmp/cache, /db (skips dirs that aren't
   mounted)
5. Writes HOME, HF_HOME, and XDG_CACHE_HOME into
   /run/s6/container_environment/ — the idiomatic s6-overlay way to propagate
   env vars to all subsequent with-contenv service scripts, eliminating
   spurious cache-write warnings

The frigate and go2rtc service run scripts use s6-setuidgid frigate to
drop privileges before exec-ing the process. Because s6-setuidgid is passed
a username rather than a raw uid, it reads the full group membership of frigate
from /etc/group at exec time — picking up the supplementary groups added in
step 3.

nginx and certsync remain root — nginx needs root to bind port 443 and
generate TLS certificates; it drops its workers to nobody itself.

Startup sequence with PUID/PGID set

base
 └─► user-setup  [root] → adjusts uid/gid, propagates supplementary groups,
 │                         chowns data dirs, updates s6 container environment
 ├─► prepare       [root]  → config migration
 └─► log-prepare   [root]  → creates /dev/shm/logs/* for s6-log (nobody)
       go2rtc      [frigate uid+groups] → s6-setuidgid frigate go2rtc
       │             └─► ffmpeg subprocesses inherit uid+groups
       frigate      [frigate uid+groups] → s6-setuidgid frigate python3 -m frigate
       │             └─► ffmpeg subprocesses inherit uid+groups
       nginx        [root]  → generates certs, binds ports

Supplementary group handling

Hardware acceleration and devices (VAAPI, NVENC, Coral USB) require the app
process to be a member of specific groups (e.g. video, render). Docker's
group_add: injects these into the container's init process. Without explicit
propagation, s6-setuidgid would reset to only the frigate user's own groups,
breaking device access.

user-setup iterates id -G (skipping gid 0 / root) and calls
usermod -aG <group> frigate for each, so they are in place before any
s6-setuidgid frigate call. The underlying gid numbers are preserved exactly —
no remapping occurs.

Backward compatibility

When PUID/PGID are not set, user-setup exits immediately (no-op).
All behaviour is identical to today — Frigate runs as root. This is a fully
opt-in change.

Files changed

File	Change
docker/main/Dockerfile	Add frigate user/group (uid/gid 1000 as placeholder)
rootfs/…/user-setup/run	New — PUID/PGID setup, group propagation, env vars
rootfs/…/user-setup/type	New — oneshot
rootfs/…/user-setup/up	New — s6-rc exec pointer
rootfs/…/user-setup/dependencies.d/base	New — depends on base bundle
rootfs/…/prepare/dependencies.d/user-setup	New — waits for user-setup
rootfs/…/log-prepare/dependencies.d/user-setup	New — waits for user-setup
rootfs/…/frigate/run	Drop to s6-setuidgid frigate when PUID≠0
rootfs/…/go2rtc/run	Same — covers ffmpeg processes spawned by go2rtc

Usage

services:
  frigate:
    image: ghcr.io/blakeblackshear/frigate:stable
    environment:
      - PUID=1000   # host user uid  (run: id -u)
      - PGID=1000   # host user gid  (run: id -g)
    group_add:
      - "44"        # video  — for VAAPI / V4L2
      - "105"       # render — for /dev/dri/renderD128
    volumes:
      - /path/to/config:/config
      - /path/to/media:/media/frigate

Files created by Frigate (recordings, clips, database) will be owned by
uid/gid 1000 on the host. Hardware-accelerated ffmpeg processes retain access
to /dev/dri/* and other devices via the propagated supplementary groups.

Testing

Verified against Frigate stable (0.17.1-416a9b7):

• Container reaches healthy with PUID=1000 PGID=1000
• python3 -m frigate and all child processes run as uid/gid 1000
• go2rtc binary runs as uid/gid 1000; its ffmpeg children inherit the same
• Supplementary groups from group_add: (e.g. video gid 44) are correctly
  propagated — verified via /proc/<pid>/status Groups: field
• Root group (gid 0) is explicitly excluded from propagation
• /config, /media, /db, /tmp/cache correctly owned after startup
• No HOME/HuggingFace/OpenVINO cache warnings in logs
• Without PUID/PGID: zero behaviour change — runs as root as before
• Config migration, database writes, FastAPI all function normally

puid-pgid-support-git.patch

[hawkeye217]

What you've proposed is not all that different than what we had in mind, with some slight differences. We've planned this and other container hardening work for a future version of Frigate.