Network and security
The app asks for a sign-in by default, because an Immich API key gives it access to the library. A proxy or render worker is part of that trust boundary. The first start generates a password; Authentication says where to find it.
Listen on the right address
A pip or uv install binds to 127.0.0.1 by default, with the generated sign-in.
ui --host 0.0.0.0 opens it to the LAN, still behind the sign-in.
In Docker, the image starts with ui --host 0.0.0.0. The shipped Compose mapping
127.0.0.1:22830:8080 keeps it reachable from the host alone.
For LAN access, follow
Docker's login and mapping steps.
With sign-in turned off on purpose (IMMICH_MEMORIES_AUTH__ENABLED=false), the UI binds to
localhost unless you pass an explicit host.
An explicit ui --host 0.0.0.0 or IMMICH_MEMORIES_SERVER__HOST=0.0.0.0 then exposes an app with
no login: anyone reaching that port can use its Immich access. Use these only on a restricted
network. A YAML server.host: 0.0.0.0 is ignored.
To reach the app from the LAN, keep the sign-in, or put your own auth proxy in front and let it sign users in with a header (trusted header sign-in).
Allowed hosts
Every request names a host in its Host header. With sign-in on, the app answers any host: the sign-in protects it. With sign-in off, it answers only these:
localhost,127.0.0.1,[::1]andhost.docker.internal, on any port;server.host, when it is a name or a specific address (not0.0.0.0or::);- the host of
auth.public_url; - every entry of
server.allowed_hosts.
Any other host gets 421 Misdirected Request. Without this, a web page on another site could point its own name at your machine and read the app as if it were that site.
With sign-in on you can still set server.allowed_hosts or auth.public_url; either one restricts
requests to the public URL's hostname, the listed entries and the localhost names above. Other
names get 421 Misdirected Request.
/health/live and /health/ready answer whatever host they name, since Kubernetes probes use the
pod IP. A host the app would otherwise refuse gets the status field and nothing else, in every auth
mode, so a page that rebinds its own name to your machine can't read the automation state. An
allowed host gets status and version; the automation, delivery, disk and Immich detail goes only
to a signed-in session, or to anyone when sign-in is off. The compatibility /health
endpoint keeps the host checks above: a pod-IP request can receive 421. Use the dedicated
liveness and readiness paths for Kubernetes probes.
To have the app answer to extra names (a proxy's public name, say), list them:
advanced:
server:
allowed_hosts: [nas.lan, 192.168.1.20]
Ports in allowed_hosts are ignored: nas.lan covers nas.lan:8080. The environment form is
IMMICH_MEMORIES_SERVER__ALLOWED_HOSTS='["nas.lan"]'. The first refusal for each host is logged
as a warning.
Writes from other sites
A POST, PUT, PATCH or DELETE under /api or /auth that a browser sends from another
site is refused with 403, with auth on or off. The browser's Sec-Fetch-Site header decides
when it is present; otherwise an Origin that differs from the request's host is refused.
Calls without either header (curl, CronJobs, the CLI) pass, so POST /api/trigger with its token
still works.
Every HTTP request accepts a body up to 4 MiB, including reads and sign-in pages. Larger requests receive 413 Content Too Large, including streamed requests without a content length.
Uploaded soundtracks have a separate limit: 64 MiB each, refused before the body is read when the request
announces more. Together they may use server.music_upload_quota_mb (default 1024); past it the
oldest uploads are removed.
No page may show the app in a frame: every response carries X-Frame-Options: DENY and
Content-Security-Policy: frame-ancestors 'none'.
HTTPS reverse proxy
This example uses nginx on the same host, proxying the shipped loopback mapping. Enable
Basic auth or OIDC first. Replace APP_HOST_PORT in the nginx config
with your published host port: 22830 with the release Compose file, or the port you
chose. Configure the app:
advanced:
auth:
public_url: https://memories.example.com
trusted_proxies: [127.0.0.1]
server:
secure_cookies: true
The app must trust the peer address it actually sees. Docker's bridge may make that the host
bridge address instead of 127.0.0.1; replace it with that exact address. For a proxy container,
use its fixed address and keep the app off published LAN ports.
On a Linux Docker host, inspect the app's container IP and observe a proxied connection:
docker inspect --format '{{json .NetworkSettings.Networks}}' "$(docker compose ps -q immich-memories)"
sudo tcpdump -nn -i any 'tcp dst port 8080'
Open the UI through the proxy while the capture runs. Find the packet whose destination is
the app's container IP; its source is the peer the app must trust. Stop the capture with Ctrl-C.
For example, 172.20.0.1 > 172.20.0.3.8080 means trust 172.20.0.1, not the browser address
in X-Forwarded-For. With Docker Desktop, a proxy container on the app's private network with
a fixed IP avoids relying on the host-to-VM bridge address.
server {
listen 443 ssl;
server_name memories.example.com;
ssl_certificate /etc/nginx/tls/fullchain.pem;
ssl_certificate_key /etc/nginx/tls/privkey.pem;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:APP_HOST_PORT;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_read_timeout 300s;
proxy_buffering off;
}
}
This recipe overwrites forwarded headers with the immediate client's values. If another trusted proxy sits in front, configure that chain explicitly. For header authentication, also discard client-supplied identity headers and set them only from the proxy's verified session.
Register OIDC callback https://memories.example.com/auth/callback. Allow only intended verified
emails/domains. App logout redirects to the IdP's end-session endpoint when available, without
a post_logout_redirect_uri.
FORWARDED_ALLOW_IPS, when set, overrides auth.trusted_proxies. With auth on, the app refuses
to start when it is * (it would let every client choose its own address); list your proxy's
address instead. With provider: header remove the variable entirely, even if empty, and
configure auth.trusted_proxies. Only uvicorn reads
X-Forwarded-For, and only from those proxies: the sign-in limiter counts failures on the address
uvicorn resolved, never on a header the client sent.
Enable secure cookies only once users reach HTTPS; plain HTTP LAN logins then fail.
A proxy in Docker
These recipes use the app's Basic auth, with TLS handled by your existing proxy.
Set IMMICH_MEMORIES_AUTH_USERNAME and IMMICH_MEMORIES_AUTH_PASSWORD in .env first,
following authentication. Do not substitute a proxy's login page for
app authentication. OIDC can use the same network, with its callback registered as above.
Header authentication needs a verified identity provider and the separate
header-auth rules; these examples do not configure it.
Shared network and app settings
Pick an unused subnet; 172.30.80.0/24 is just an example. Create a network used only by
this app and its proxy:
docker network create --subnet 172.30.80.0/24 memories-proxy
In the app's Compose file, remove the whole ports: block. Add this network to
immich-memories, keeping its existing default network, volumes and environment:
services:
immich-memories:
networks:
default: {}
memories-proxy:
ipv4_address: 172.30.80.3
networks:
memories-proxy:
external: true
Add the same external network to your proxy's Compose file. Replace proxy with its existing
service name and keep its other networks and settings:
services:
proxy:
networks:
default: {}
memories-proxy:
ipv4_address: 172.30.80.2
networks:
memories-proxy:
external: true
The two nonempty username/password environment values above enable Basic auth.
In the app's config.yaml, merge these settings into advanced:
advanced:
auth:
public_url: https://memories.example.com
trusted_proxies: [172.30.80.2]
server:
secure_cookies: true
allowed_hosts: [memories.example.com]
Trust the proxy's single address, not the entire Docker subnet or *. Only the proxy
publishes HTTP/HTTPS ports; neither the browser nor another LAN client reaches port 8080
directly. Preserve the public Host and browser Origin headers. Rewriting either to the
container name breaks same-origin writes; stripping Origin defeats that check.
Before trusting the address, temporarily add FORWARDED_ALLOW_IPS: "" to the app's Compose
environment and recreate the app. This disables forwarded-address rewriting for Basic auth.
Request https://memories.example.com/health/live, then inspect:
docker compose logs --tail 50 immich-memories
The uvicorn.access line for GET /health/live must show 172.30.80.2:<port> as its client.
If it shows something else, check the proxy's network attachment and trust the observed peer
only after identifying it. Remove that temporary environment entry, then recreate the app
again. Once forwarding is trusted, access logs show the browser address instead; that is
not the Docker peer to put in trusted_proxies.
Nginx Proxy Manager
Attach your existing NPM service to memories-proxy as above. Create a Proxy Host:
- Domain:
memories.example.com; scheme:http. - Forward hostname:
immich-memories; forward port:8080. - Request a certificate and enable Force SSL.
- Leave Websockets Support off. Progress uses server-sent events (SSE).
In that Proxy Host's Advanced field, add:
proxy_buffering off;
proxy_read_timeout 300s;
client_max_body_size 100m;
Do not add another location / or replace NPM's generated Host/forwarded headers.
Disabling buffering lets progress events reach the browser as they arrive.
NPM's Docker-network guidance
explains service-name routing without published upstream ports; nginx documents
response buffering.
Caddy
Attach your existing Caddy service to memories-proxy, then add this site to its Caddyfile:
memories.example.com {
reverse_proxy immich-memories:8080
}
Caddy handles HTTPS for the public name. Its default HTTP upstream preserves Host, supplies
forwarded headers and flushes text/event-stream responses immediately. No WebSocket or
buffering workaround is needed. Validate before reload with caddy validate --config /etc/caddy/Caddyfile.
See Caddy's reverse-proxy defaults and streaming behavior.
Traefik
Attach your existing Traefik service to memories-proxy. These labels go under the app's
immich-memories service, alongside its private network attachment:
labels:
- "traefik.enable=true"
- "traefik.docker.network=memories-proxy"
- "traefik.http.routers.memories.rule=Host(`memories.example.com`)"
- "traefik.http.routers.memories.entrypoints=websecure"
- "traefik.http.routers.memories.tls=true"
- "traefik.http.routers.memories.tls.certresolver=letsencrypt"
- "traefik.http.routers.memories.service=memories"
- "traefik.http.services.memories.loadbalancer.server.port=8080"
- "traefik.http.services.memories.loadbalancer.passhostheader=true"
- "traefik.http.services.memories.loadbalancer.responseforwarding.flushinterval=-1ms"
Use your existing HTTPS entrypoint and certificate resolver names in place of websecure
and letsencrypt. The Docker provider must be enabled. Do not attach a buffering middleware
or set forwardedHeaders.insecure=true. Keep the default public Host; the negative flush
interval sends progress without batching. Traefik documents the
Docker labels
and response forwarding.
Check the route before rendering
Run docker compose config --quiet in both stacks, then recreate the app and proxy. Visit the
HTTPS name: sign-in must work, a Settings save must succeed, and progress must update during a
render without arriving in one lump at the end. An unrelated browser origin must still get
403 for writes; do not fix that refusal by stripping headers. Check that
docker compose port immich-memories 8080 reports no published port.
The Caddy, Nginx Proxy Manager and Traefik recipes were run against the real app with exactly these checks; tested deployments lists the versions. With OIDC, header authentication or a public ACME certificate, run the same checks on your own setup.
These recipes use the standard public HTTPS port 443. NPM's generated Host header drops
a nonstandard public port: a browser Origin such as https://memories.example.com:8443 can
then get 403 on writes. Use a public 443 mapping with this recipe; do not strip Origin to
work around it.
If you try one, report your proxy version, host platform and the checks that passed or failed.
Ports and egress
| Connection | Default port | Needed when |
|---|---|---|
| Browser/proxy to Compose host | 22830 | Published Compose port |
| App listener (native or container) | 8080 | All installs |
| App to Immich | 2283, or your HTTPS proxy | Always |
| App to PostgreSQL | 5432 | PostgreSQL store |
| App to inference/captions | 8092 | Configured model services |
| App to Ollama | 11434 | Reader endpoint uses it |
| App to another reader | Its configured port, often 8000/9999 | That reader |
| App to render worker | 8093 standalone; 8092 with /render in the unified worker | Remote rendering |
| DNS / HTTPS downloads | 53 / 443 | Name resolution / explicit setup downloads |
App to api.github.com | 443 | Update check: when you ask, or daily with updates.check_daily (off by default) |
Other music, map and notification endpoints use their configured ports. Exact payloads and destinations. The Kubernetes base allows ports, not hosts. Custom reader/worker ports require a policy patch; PostgreSQL needs the 5432 patch. Terraform does not create a NetworkPolicy.
Secrets with different jobs
| Secret | Purpose |
|---|---|
| Immich API key | Reads the library and optional generated-film delivery |
IMMICH_MEMORIES_SECRET_KEY | Decrypts credentials saved in Settings; preserve with backups |
IMMICH_MEMORIES_STORAGE_SECRET | Signs browser sessions; rotating it signs users out |
server.trigger_token | Authenticates automation triggers |
render.worker_token | Authenticates the worker; worker also receives the Immich key |
Prefer HTTPS for services beyond loopback. Review access to deployment Secrets, Terraform state, backup files and worker hosts as access to your library.
Settings only the operator sets
Someone who reaches the Settings page shouldn't be able to choose a program the server runs, a
file it overwrites, or the host that receives your Immich keys. These keys are read only from
config.yaml or the environment, and take effect on restart:
render.worker_base_url,render.worker_token;llm.local_server;triage.encoder,free_text.wordnet,editorial.laya_checkpoint;editorial.preparation.detector_python,editorial.preparation.detector_cache_dir,editorial.preparation.marqo_onnx.
The settings API refuses them. A value already saved in the store is ignored at startup with a
warning; move it to config.yaml or the environment.
Configured service addresses
Reader, caption, inference, geocoding, music and render-worker endpoints must use HTTP or HTTPS.
Notification URLs use Apprise's supported schemes. Loading configuration or saving Settings
rejects literal link-local addresses (169.254.0.0/16, fe80::/10, including mapped IPv4).
Ordinary private LAN addresses remain supported.
An operator who needs a link-local service can set IMMICH_MEMORIES_ALLOW_LINK_LOCAL_URLS=true
in the app's process environment and restart it. Settings cannot change this override. This is
a guard against accidental configuration: it does not resolve DNS names or inspect redirects.
The project threat model lists the trust boundaries and accepted deployment limits.