Update docs

This commit is contained in:
Alan Grainger
2026-10-08 20:40:21 +13:00
parent 885ecfb7bc
commit ac83705fd7
3 changed files with 97 additions and 3 deletions
+1
View File
@@ -90,6 +90,7 @@ export default async () => defineConfigWithTheme<ThemeConfig>({
{
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' },
+6 -3
View File
@@ -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:
<img src="/server-settings.png" width="400" height="182" alt="Immich server settings - external domain">
+90
View File
@@ -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.