From ac83705fd7a186076c80e7cb1ae4d326afe0074d Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Thu, 8 Oct 2026 20:40:21 +1300 Subject: [PATCH] Update docs --- docs/.vitepress/config.ts | 1 + docs/installation.md | 9 ++-- docs/reverse-proxy.md | 90 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 97 insertions(+), 3 deletions(-) create mode 100644 docs/reverse-proxy.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index cdb86e9..6e11b09 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -90,6 +90,7 @@ export default async () => defineConfigWithTheme({ { text: 'Guides', items: [ + { text: 'Put IPP behind a reverse proxy', link: '/reverse-proxy' }, { text: 'Let visitors send photos back', link: '/visitor-uploads' }, { text: 'Tag and review visitor uploads', link: '/tag-and-review-uploads' }, { text: 'Single domain with Immich', link: '/running-on-single-domain' }, diff --git a/docs/installation.md b/docs/installation.md index 2641b4d..6ac6b86 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -15,14 +15,17 @@ slash (example `https://your-proxy-url.com`). If you remove this value, it will dynamically generate it based on the request hostname. This can be useful if you are [serving from multiple domains](/running-on-single-domain). -4. Start the docker container. You can test that it is working by visiting - `https://your-proxy-url.com/share/healthcheck`. Check the container console output for any error messages. +4. Start the docker container. Check the container console output for any error messages. ```bash docker-compose up -d ``` -5. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve +5. Point your reverse proxy at the container on port 3000, so IPP is served over HTTPS at your `PUBLIC_BASE_URL`. + See [Put IPP behind a reverse proxy](/reverse-proxy) for Caddy, nginx and Traefik examples. You can test that it + is working by visiting `https://your-proxy-url.com/share/healthcheck`. + +6. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve Immich Public Proxy: Immich server settings - external domain diff --git a/docs/reverse-proxy.md b/docs/reverse-proxy.md new file mode 100644 index 0000000..872c1db --- /dev/null +++ b/docs/reverse-proxy.md @@ -0,0 +1,90 @@ +# Put IPP behind a reverse proxy + +IPP listens on plain HTTP on port 3000 and expects a reverse proxy in front of it to terminate TLS and give it a public +hostname. Any proxy will do. This page gives the minimal config for the common ones and the few things IPP needs from +whichever you use. + +## What the proxy must do + +- **Terminate TLS** and forward every request to the IPP container on port 3000. The gallery uses relative URLs, so + no path rewriting is needed, and IPP serves from the root of its hostname or from `/share` and `/s` on a domain it + shares with Immich. +- **Match `PUBLIC_BASE_URL`.** Set [`PUBLIC_BASE_URL`](/config/environment-variables#public_base_url) on the IPP + container to the public `https://` address the proxy serves it on. IPP uses it for the `og:image` tag that messaging + apps read for link previews. Without it, IPP builds that URL from the request it receives, which behind a + TLS-terminating proxy is plain `http://`. If you must leave it unset, make sure the proxy forwards the original + `Host` header. +- **Allow large uploads** only if you run the [upload service](/visitor-uploads). IPP itself needs no request size + settings. See [Request size limits](/visitor-uploads#request-size-limits). + +The examples reach the container as `immich-public-proxy:3000`, which works when the proxy shares a Docker network +with it. From the host, use the published port instead: `localhost:3000` with the default compose file. + +## Caddy + +``` +photos.example.com { + reverse_proxy immich-public-proxy:3000 +} +``` + +Caddy obtains the certificate and forwards the `Host` header on its own. + +## nginx + +```nginx +server { + listen 443 ssl; + server_name photos.example.com; + + location / { + proxy_pass http://immich-public-proxy:3000; + proxy_set_header Host $host; + } +} +``` + +Add your `ssl_certificate` lines as for any other site. + +## Traefik + +A dynamic configuration file, in the same style as the [mTLS guide](/securing-immich-with-mtls#using-traefik): + +```yaml +http: + services: + ipp: + loadBalancer: + servers: + - url: "http://immich-public-proxy:3000" + + routers: + ipp: + entryPoints: + - websecure + service: ipp + rule: "Host(`photos.example.com`)" + tls: + certResolver: letsencrypt +``` + +## Cloudflare + +If Cloudflare proxies the domain, set the `/share/video/*`, `/share/*/download` and `/s/*/download` paths to +**Bypass Cache**, otherwise video playback and zip downloads can fail. Cloudflare also refuses request bodies over +100 MB on the Free and Pro plans, which matters only for the [upload service](/visitor-uploads#request-size-limits). + +## Check it + +Visit `https://photos.example.com/share/healthcheck`. It returns `ok` when the proxy reaches IPP and IPP reaches +Immich. If link previews in a messaging app show `http://` or a private address, see +[Troubleshooting](/troubleshooting#link-previews-show-http-or-a-private-ip). + +## Other recipes + +- [Single domain with Immich](/running-on-single-domain): send only `/share/*` and `/s/*` to IPP. +- [Let visitors send photos back](/visitor-uploads#route-it-through-your-reverse-proxy): route the upload service as + a path or its own hostname. +- [Redirect root domain to a share](/redirect-root-to-share). +- [Custom error pages from the proxy](/config/error-responses#customising-the-response-using-your-reverse-proxy). +- [Securing Immich with mTLS](/securing-immich-with-mtls): lock Immich itself down so only IPP is public.