[Feature] Support serving Immich under a sub-path (e.g. /immich) via reverse proxy

[VrushankPatel]

I have searched the existing feature requests, both open and closed, to make sure this is not a duplicate request.

• Yes

The feature

Title:
Support for serving Immich under a sub-path (e.g. https://domain.com/immich) via reverse proxy

Use case:
I run multiple self-hosted services behind a single Nginx reverse proxy. For example:

• https://domain.com/portainer → service at port 9000
• I want https://domain.com/immich → Immich backend at port 2283

This is convenient because I don’t want to allocate a separate sub-domain for Immich. I already have domain.com in use and other services under paths.

Problem:
When I attempt to proxy Immich via Nginx using location /immich { … } proxy_pass http://internal:2283; }, I encounter issues:

• The UI loads but many assets (JS/CSS) or API endpoints fail because paths assume root (/).
• Web socket or API calls seem to reference root paths instead of /immich/....
• I could not locate any documented BASE_URL or SUB_PATH environment variable in Immich’s docs or .env that allows this path prefixing.
• The official docs show reverse proxy examples but always at root of domain/sub-domain. ([Immich][2])

How we expect it to be:

• Immich should support being served under a path prefix (e.g. /immich) without breaking UI, API or socket connections.

• There should be a documented environment variable (for example BASE_PATH, WEB_BASE_URL, APP_CONTEXT_PATH, etc) or configuration option in docker-compose/.env to set this prefix.

• Example: In .env, IMMICH_BASE_PATH=/immich. The server would serve static assets and API routes prefixed accordingly, and the web UI would generate correct URLs with the prefix.

• In the Nginx config, one could do:

  location /immich/ {
    proxy_pass http://localhost:2283/;  # note proxypass trailing slash
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

• Should support both web UI and mobile app usage when the server endpoint URL includes the path: https://domain.com/immich.

Possible env variables / docker-compose suggestions:
In docker-compose.yml / .env:

# existing variables
UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres
IMMICH_VERSION=v2.2.3
# new proposed
IMMICH_BASE_PATH=/immich
IMMICH_PUBLIC_URL=https://domain.com/immich

In docker-compose.yml service for immich-server:

environment:
  - UPLOAD_LOCATION=${UPLOAD_LOCATION}
  - DB_DATA_LOCATION=${DB_DATA_LOCATION}
  - IMMICH_VERSION=${IMMICH_VERSION}
  - IMMICH_BASE_PATH=${IMMICH_BASE_PATH}
  - IMMICH_PUBLIC_URL=${IMMICH_PUBLIC_URL}
ports:
  - "2283:2283"

In documentation, specify that if IMMICH_BASE_PATH is set (non-empty), the server will internally mount its web assets and API under that path. Also update routing for websockets (e.g. /socket.io/…) accordingly.

Trade-offs / considerations:

• This is non-trivial: many front-end assets, routing logic, API endpoints assume root path; updating may require significant changes in both server and web UI.
• Mobile clients may expect root path and may break if prefixing is inconsistent.
• Backward compatibility: existing installations at root must continue working without changes.
• Documentation must highlight that reverse proxy prefixing is experimental if not fully stable.
• Until full support is implemented, a sub-domain (e.g. immich.domain.com) remains the recommended approach.

Steps to reproduce / environment:

1. Deploy Immich (version: e.g. v2.2.3) via docker-compose on internal port 2283.
2. Configure Nginx such that domain.com/immich proxies to internal 2283.
3. Access https://domain.com/immich in browser.
4. Observe missing assets, 404s for /immich/static/..., websocket connection fails, API calls to /api/... rather than /immich/api/....
5. Check logs of the server for routing errors.

Additional info:

• OS: e.g. Ubuntu 22.04, Docker 20.x, Compose v2.x
• Nginx version: 1.22
• No changes made to Immich default configuration regarding base URL.

Platform

• Server
• Web
• Mobile

[bo0tzz]

#1679