Deployment

Use the published Docker image for production. On macOS, run natively to use Metal.

For the Compose file and first-run setup, see Getting started. The container runs as UID and GID 10001.

Image tags

haavardnk/immich-edit publishes:

  • Exact semantic versions such as 0.5.1
  • Moving minor and major tags such as 0.5 and 0
  • latest for the newest stable release
  • edge for the newest commit on main that passed CI, built between releases and not for production use

Every image supports Linux amd64 and arm64.

Reverse proxy

After first-run setup, keep immich-edit on a private network or loopback address and terminate TLS with Caddy, nginx, Traefik, or another reverse proxy. Immich authentication is built in; no separate authentication proxy is required. TLS also turns on browser previews: browsers only offer WebGPU to HTTPS pages and localhost. See browser previews on a local network.

Forward Host, X-Forwarded-For, and X-Forwarded-Proto. The backend believes forwarding headers only from the peers in TRUSTED_PROXIES, which defaults to loopback and private ranges; see trusted proxies. X-Forwarded-Proto: https makes session cookies secure.

Caddy 

edit.example.com {
  reverse_proxy 127.0.0.1:3000
}

nginx 

server {
  listen 443 ssl http2;
  server_name edit.example.com;

  ssl_certificate /etc/letsencrypt/live/edit.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/edit.example.com/privkey.pem;

  client_max_body_size 200m;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Request-Id $request_id;
    proxy_read_timeout 600s;
  }
}

Keep client_max_body_size above MAX_BODY_MB when large originals pass through the proxy.

HTTPS for the installed app

immich-edit can be installed as an app on phones, tablets and computers. Browsers only install web apps, and only run the service worker that keeps the app loading offline, on an HTTPS address with a trusted certificate:

  • A plain http:// address on your network, such as http://192.168.1.20:3000, cannot install. Editing still works there; Settings > This device > Install app explains why install is unavailable.
  • A certificate warning you clicked through is not enough. The browser still treats the page as untrusted.
  • http://localhost counts as secure, but only on the computer running the server.

Two setups give every device a trusted address:

  • Tailscale Serve gives the server an HTTPS address with a publicly trusted certificate inside your tailnet. Run tailscale serve --bg 3000 on the host and open the https://<host>.<tailnet>.ts.net address on each device.
  • Caddy with tls internal issues its own certificate for a LAN address, as in browser previews on a local network. Install Caddy’s root certificate on every device you install from, and on iPhone and iPad also turn it on under Settings > General > About > Certificate Trust Settings.

Behind any proxy, keep the proxy’s address in TRUSTED_PROXIES so X-Forwarded-Proto: https is believed and the session cookie gets the Secure flag. See trusted proxies. If you sign in with OAuth, also register the HTTPS address.

GPU

The container renders on the CPU until a GPU is passed through. See GPU passthrough for AMD, Intel and NVIDIA.

Health checks

  • GET /api/health/live is an unauthenticated liveness check and returns success while the process is running.
  • GET /api/health requires a session and reports renderer, Immich, database, codec, and redacted configuration state.

The official image includes a Docker health check against /api/health/live.

Native execution

Install the dependencies from development, build the frontend, then run:

cd web
npm ci
npm run build
cd ..
WEB_DIR=web/build \
DCP_DIR=crates/backend/assets/dcp \
DATA_DIR=./data \
cargo run -p immich-edit-backend --release

See configuration for every setting and backup and upgrade before changing versions.