Update docs

This commit is contained in:
Alan Grainger
2026-10-07 16:51:46 +13:00
parent ba893dc42f
commit 7a9ff2e6ee
12 changed files with 53 additions and 66 deletions
+4 -5
View File
@@ -6,7 +6,7 @@ To avoid giving information away about your server, IPP responds with a limited
|------|-------------------------------------------------------------------------------------------------|
| 503 | Healthcheck failed: Immich is not accessible. Only on the `/healthcheck` route. |
| 401 | Invalid password provided for a password-protected share link. |
| 204 | Nothing is routed to the upload service's healthcheck path, `/upload/healthcheck` by default. The gallery probes it before showing the "Add photos" button; see [`uploadUrl`](/config/ipp-options#uploadurl). |
| 204 | No upload service at `/upload/healthcheck`. The gallery checks this path before showing the "Add photos" button; see [`uploadUrl`](/config/ipp-options#uploadurl). |
| 404 | All other invalid requests, e.g. album doesn't exist, share link is expired, non-existing file. |
Instead of sending the 404 code, you can customise that response by [changing the configuration option](/config/ipp-options#custominvalidresponse) for `customInvalidResponse`.
@@ -24,10 +24,9 @@ If you want to send a custom 404 page, you would do that with either of the belo
## Custom function
If you want to go even further, you can write your own custom function. Do this by taking a copy of the `app/dist/invalidRequestHandler.js` file,
then mounting it back as a Docker volume into the correct location for the container to use.
Take the copy from the image of the IPP major version you run. A copy from an earlier major version can fail to load.
You can also write your own function. Take a copy of `app/dist/invalidRequestHandler.js` from the image of the IPP
version you run, edit it, and mount it back into the container at the same path. A copy from an earlier major
version can fail to load.
## Customising the response using your Reverse Proxy
+4 -4
View File
@@ -63,7 +63,7 @@ Format for the [`showExpiryDate`](#showexpirydate) date, as a [dayjs format stri
**Type:** `string` · **Default:** `""`
Locale for [`showExpiryDate`](#showexpirydate) when the format uses name tokens (e.g. `MMMM` for month names), as a [dayjs locale code](https://github.com/iamkun/dayjs/tree/dev/src/locale) such as `"de"`, `"fr"` or `"en-gb"`. The default (`""`) is dayjs's default English. The numeric default format needs no locale. Applies only to this server-rendered date; thumbnail date-group headers ([`groupByDate`](#groupbydate)) already follow each viewer's own browser locale.
Language for the [`showExpiryDate`](#showexpirydate) date when the format uses names (e.g. `MMMM` for month names), as a [dayjs locale code](https://github.com/iamkun/dayjs/tree/dev/src/locale) such as `"de"`, `"fr"` or `"en-gb"`. The default is English. The default numeric format needs no locale. The date-group headers from [`groupByDate`](#groupbydate) follow each visitor's own browser language instead.
## `groupByDate`
@@ -75,16 +75,16 @@ Group the gallery's thumbnails by date, with a header above each group.
- `"month"` - month headers like "December 2024".
- `"day"` - day headers like "Wed, 25 Dec 2024" (matching Immich's own timeline format).
Grouping uses each photo's local "taken" date (matching Immich's own timeline). Photos follow the album's own sort order from Immich - "Oldest first" puts the earliest group at the top, "Newest first" the most recent - and default to newest-first for shares with no album order. Items missing a creation date end up under an "Undated" bucket at the end (or render without any header when the whole gallery is undated).
Grouping uses the date each photo was taken, as in Immich's own timeline. Groups follow the album's sort order in Immich, and newest first for shares without one. Photos with no date go under an "Undated" header at the end.
## `showDownloadZip`
**Type:** `bool` · **Default:** `true`
Show the bulk-zip download UI - the "download all" button in the header and the multi-select download toolbar. Only takes effect when downloads are also allowed by [`allowDownload`](/config/ipp-options#allowdownload). Set to `false` to hide the zip download while still offering per-asset downloads via the lightbox ([`lightbox.showDownload`](/config/lightbox#showdownload)).
Show the "download all" button in the header and the multi-select download toolbar. Only takes effect when downloads are allowed by [`allowDownload`](/config/ipp-options#allowdownload). Set to `false` to hide zip downloads while still offering single downloads in the lightbox ([`lightbox.showDownload`](/config/lightbox#showdownload)).
## `cacheTime`
**Type:** `int` · **Default:** `300`
How long (in seconds) browsers and any CDN may cache the gallery **page** before revalidating. Set this longer to reduce load on your server, but be aware that if you add new photos to a gallery they won't show up until the cache times out or you manually clear any downstream caches.
How long, in seconds, browsers and any CDN may cache the gallery page. A longer time means less load on your server, but new photos added to a share will not show for visitors until it runs out.
+1 -1
View File
@@ -17,7 +17,7 @@ Connection settings (the Immich URL, public URL, port and config file location)
## How to provide a config override
> [!NOTE]
> You only need to include the keys you're changing. Anything you omit keeps its default, and the defaults are always the most privacy-respecting option. In particular the metadata groups are per-field opt-in: nothing is exposed until you set its flag to `true`, including fields IPP adds in future versions.
> You only need to include the keys you're changing. Anything you omit keeps its default, and the defaults are always the most private option. Nothing in the [metadata](/config/metadata) groups is shown until you set its flag to `true`.
There are two ways to supply custom config. If both are present, `CONFIG` wins and the file is not read.
+13 -13
View File
@@ -19,9 +19,9 @@ Serve full-resolution images both when zooming in the lightbox and when download
**Type:** `object`
Change the headers sent with your web responses. The default is a 30-day `Cache-Control` and a permissive CORS header.
These apply to photos, videos and static files. The "download all" zip is always sent with `Cache-Control: no-store`
to prevent CDN issues, and the gallery page uses its own [`gallery.cacheTime`](/config/gallery#cachetime).
Change the headers sent with photos, videos and static files. The default is a 30-day `Cache-Control` and a
permissive CORS header. The "download all" zip is always sent with `Cache-Control: no-store`, and the gallery page
uses its own [`gallery.cacheTime`](/config/gallery#cachetime).
```json
{
@@ -51,11 +51,11 @@ Highest quality served for a download (the download button and "download all" zi
Highest quality the lightbox loads when you zoom in past fit-to-screen.
- `"preview"` - keep the preview (default; zoom is capped to the preview's real pixels).
- `"fullsize"` - upgrade to the full-resolution browser-displayable image on zoom, à la the Immich web viewer.
- `"fullsize"` - load the full-resolution browser-displayable image on zoom, like the Immich web viewer.
`"original"` is intentionally not an option (it could be an unviewable RAW/DNG or a huge file).
`"original"` is not an option here, because an original can be a RAW or DNG file the browser cannot display.
**Independent of [`allowDownload`](#allowdownload)** - your download UI can be off while zoom is on. It only does anything where Immich can serve full resolution: the share's **own** "allow downloads" toggle in Immich must be on (the full-res image comes from the original file, which Immich gates on that toggle), and the format must be **web-displayable** (JPEG/PNG/WebP). Otherwise (RAW/HEIF, or a share with Immich downloads off) the lightbox stays on the preview. To enable zoom-up, leave the Immich share's download permission on and use [`allowDownload`](#allowdownload) to control whether the download buttons appear.
This setting is independent of [`allowDownload`](#allowdownload): the download buttons can be off while zoom is on. The full-resolution image is only available when the share's own "Allow downloads" toggle in Immich is on, and the photo is a JPEG, PNG or WebP. For other formats, or shares with downloads off in Immich, the lightbox stays on the preview. To get full-resolution zoom without showing download buttons, leave downloads on in Immich and set [`allowDownload`](#allowdownload) to `0`.
## `motionPhotos`
@@ -87,7 +87,7 @@ The filename of the downloaded image.
**Type:** `int` · **Default:** `0`
Show the download UI - the "download all" zip, the multi-select download, and the per-asset download button in the lightbox. Purely a UI switch; it has no effect on image quality (see [`maxZoomQuality`](#maxzoomquality) / [`maxDownloadQuality`](#maxdownloadquality)).
Show the download buttons: the "download all" zip, the multi-select download, and the download button in the lightbox. This only shows or hides the buttons; image quality is set by [`maxDownloadQuality`](#maxdownloadquality) and [`maxZoomQuality`](#maxzoomquality).
- `0` - downloads off.
- `1` - follow the Immich share's own download setting ([example](https://github.com/user-attachments/assets/79ea8c08-71ce-42ab-b025-10aec384938a)).
@@ -96,13 +96,13 @@ Show the download UI - the "download all" zip, the multi-select download, and th
The bulk-zip and per-asset buttons can be toggled independently once downloads are allowed - see [`gallery.showDownloadZip`](/config/gallery#showdownloadzip) and [`lightbox.showDownload`](/config/lightbox#showdownload).
> [!NOTE]
> With `2`, IPP shows the download UI even on shares whose **own** download toggle in Immich is off - but Immich still refuses to serve those shares' original files, so IPP works around it where it can:
> With `2`, IPP shows the download buttons even on shares whose own download toggle in Immich is off. Immich still refuses to serve those shares' original files, so on such a share:
>
> - **Videos** are downloaded as the transcoded playback file instead of the original (the same stream the visitor can already watch). The filename extension follows the transcoded format, typically `.mp4`.
> - **Photos** download normally as long as [`maxDownloadQuality`](#maxdownloadquality) is below `original`; with `maxDownloadQuality: original` they fail, because the original file is exactly what Immich is refusing to serve.
> - **Gifs** always download as the original file (their preview is a static frame), so they fail on these shares.
> - **Videos** download as the playback version, usually an `.mp4`, instead of the original.
> - **Photos** download at [`maxDownloadQuality`](#maxdownloadquality) if it is below `original`. With `original` they fail.
> - **Gifs** always download as the original file, so they fail.
>
> To guarantee full-quality downloads of everything, leave the share's download permission on in Immich.
> To be sure every download works at full quality, leave the share's download permission on in Immich.
## `uploadUrl`
@@ -110,7 +110,7 @@ The bulk-zip and per-asset buttons can be toggled independently once downloads a
Where the optional upload service (the `immich-public-proxy-upload` container) is served. A share whose "Allow public user to upload" option is on in Immich then shows an "Add photos" button in the gallery header, which opens that share's page on the upload service. To set up the service, see [Let visitors send photos back](/visitor-uploads).
- **A path**, such as the default `/upload`, means the service is on IPP's own hostname under that path. Before showing the button, the gallery page checks that the upload service answers `ok` at `<path>/healthcheck`, so an install without the upload container never shows a dead button. When nothing is routed there, IPP answers that path itself with an empty 204 rather than a 404, so the check is neither a browser console error nor a hit on the [404 policy](/config/error-responses).
- **A path**, such as the default `/upload`, means the service is on IPP's own hostname under that path. Before showing the button, the gallery page checks that the upload service answers `ok` at `<path>/healthcheck`, so an install without the upload container never shows a dead button. When nothing is routed there, IPP answers that path itself with an empty 204.
- **An absolute URL**, such as `https://upload.example.com`, means the service has a hostname of its own. It is trusted without a check. The URL may include a path, such as `https://photos.example.com/upload`, which points at the same place as the default but without the check.
- **An empty string** never shows the button.
+1 -1
View File
@@ -32,7 +32,7 @@ Show a download button in the lightbox toolbar. Only takes effect when downloads
**Type:** `bool` · **Default:** `false`
Show prev/next arrows on mobile (under 640px viewport). Off by default since swipe is the natural mobile navigation.
Show prev/next arrows on mobile (screens under 640px wide). Off by default, as visitors swipe instead.
## `autoPlayVideos`
+4 -4
View File
@@ -36,11 +36,11 @@ Show the description in the sidebar only (not as a lightbox caption), expose cam
| `exif` | `object` | Camera / file EXIF group. Per-field opt-in flags, all default `false`. See [EXIF group](#exif-group). |
| `location` | `object` | Location group (city / state / country / GPS). Per-field opt-in flags, all default `false`. See [Location group](#location-group). |
Every per-field flag defaults to `false`. A field is sent to the client only when its flag is explicitly `true`. There is no master switch - this is deliberate, so that fields IPP adds in future releases don't auto-expose without your action.
Every field defaults to `false` and is sent to visitors only when its flag is `true`. There is no master switch, so a field IPP adds in a future release stays hidden until you turn it on.
The share owner's **"Show metadata"** toggle in Immich takes precedence over everything here: when it's off, IPP suppresses all description / EXIF / location output and hides the info sidebar (and its toolbar toggle) entirely, regardless of these settings.
The share's **"Show metadata"** toggle in Immich overrides everything here. When it is off, IPP hides the description, EXIF and location data and the info sidebar, whatever these settings say.
The info sidebar (and its toolbar toggle button) only appear when there is at least one section the operator has opted into - i.e. `description.sidebar` is true, or `exif` / `location` has at least one displayable field set to `true`. Dependent flags such as `exif.timeZone` do not activate the sidebar on their own. With all three groups off, the sidebar UI is suppressed.
The info sidebar and its toolbar button only appear when at least one field is turned on: `description.sidebar`, or any displayable `exif` or `location` field. `exif.timeZone` on its own does not count, as it only changes how the date is shown.
## Description
@@ -82,4 +82,4 @@ Under `ipp.showMetadata.location`. Every flag defaults to `false`, except `webLi
| `state` | `bool` | Show state / region. |
| `country` | `bool` | Show country. |
| `gps` | `bool` | Show GPS coordinates. |
| `webLink` | `bool` | Show an "Open in OpenStreetMap" link below the coordinates. The link is rendered with `rel="noreferrer"` so the share URL is not leaked to the map provider when a viewer clicks it. Has no effect unless `gps` is also true. Default `true`. |
| `webLink` | `bool` | Show an "Open in OpenStreetMap" link below the coordinates. The link does not pass the share URL on to the map provider. Has no effect unless `gps` is also `true`. Default `true`. |
+6 -7
View File
@@ -1,8 +1,8 @@
# Renamed config keys
IPP 4.0 no longer reads the old config keys below. Earlier versions mapped them to their current names at startup; 4.0
ignores them, and the option falls back to its default. Check your `config.json` for each key in the left column and
move its value to the right column. For how to update IPP itself, see [Upgrading](/upgrading).
IPP 4.0 no longer reads the old config keys below, so an option set under an old name falls back to its default.
Check your `config.json` for each key in the left column and move its value to the right column. For how to update
IPP itself, see [Upgrading](/upgrading).
## Gallery keys
@@ -40,7 +40,6 @@ ignored, so the description is hidden in both places until you change it.
gate, and each one defaults to `false`.
> [!WARNING]
> IPP will not start while either `enabled` key is in your config. A config from IPP 2.3 can have `"enabled": false`
> together with per-field flags set to `true`. Earlier versions kept those fields hidden, but 4.0 shows every field
> whose flag is `true`, GPS coordinates included. Remove the `enabled` key, and set to `true` only the fields you
> want visitors to see.
> IPP will not start while either `enabled` key is in your config. Remove the key, then check every per-field flag:
> 4.0 shows every field set to `true`, GPS coordinates included, even where `enabled` used to be `false`. Set to
> `true` only the fields you want visitors to see.