Media Gateway is a small, fail-closed publication boundary between private Immich media and public HTTP delivery. Directory conventions determine eligibility; consumer selections never grant publication authority.
Operators configure named, non-overlapping provider roots and exact directory
components such as public, public-images, public-videos or a root-scoped
post. Rules combine with OR semantics and can apply globally or to selected
logical roots. Provider paths are metadata, never local mounts.
An archive can keep its existing year/trip/device organization:
archive/
2025/trip/public-images/photo.jpg
2025/trip/public-videos/clip.mp4
2025/trip/private/photo.jpg
With matching configured conventions, the first two assets are eligible and the third remains private. No negative rule or per-asset publication database is needed. Moving media outside a matching convention revokes future requests once Immich reports the new path or lifecycle state. Revocation cannot recall bytes already received or stop an already-authorized response.
See configuration for the current publication policy schema and examples.
Public applications browse paginated collections and image/video assets through the public catalog. They receive logical root names, root-relative collection paths, filenames, validated nullable metadata and stable gateway paths. Provider absolute paths, credentials and raw EXIF stay private. Search filters narrow candidates; every candidate still passes current policy.
A consumer may store an asset ID or gateway URL, but each public delivery request independently rechecks current provider lifecycle and publication policy:
GET/HEAD /media/<id>/preview returns a fixed provider-generated image preview
or video poster.privacy.expose_source_metadata=true, GET/HEAD /media/<id>/original returns authorized provider source bytes,
including embedded EXIF/GPS. No conversion or metadata stripping is implied.The consumer guide defines pagination and projection; architecture defines media framing, provider failure handling and streaming behavior. Original source formats such as RAW/HEIC need not be browser-displayable; consumers own their downstream transformations.
By default, approved source-sensitive timestamps, coordinates and original paths are null and originals return fixed 404 without provider fetches. Previews/posters remain available. Enabling source metadata deliberately publishes the approved sensitive catalog fields and exact originals. This is not anonymity: filenames and collection names remain.
One Go binary uses strict startup TOML and a separately protected credential.
The application listens only on numeric loopback. nginx publishes the explicit
/media/ and /catalog/ routes. Immich remains private;
there is no direct NAS access, caller-selected upstream or storage fallback.
The reference deployment uses Linux amd64, an unprivileged systemd service, nginx access/error logs and sanitized application diagnostics in journald. See security, deployment and the bundle, smoke and rollback guide. Validate provider behavior on the intended host; a successful build alone is not deployment qualification.
Media Gateway does not provide a gallery/editor, media manager, CMS integration, publication database, NAS browser, generic URL proxy or identity platform. It does not offer arbitrary resize/crop/quality transformations, transcoding, HLS/DASH, a cache or a metrics stack.
Consumers own browsing, selection, presentation and consumer-specific derivative or caching strategy. The gateway surface is catalog, preview/poster and privacy-permitted exact original. A measured new need requires a fresh bounded issue; see the roadmap.