Update docs

This commit is contained in:
Alan Grainger
2026-10-08 22:33:54 +13:00
parent ecc22d2a08
commit bbff86957a
14 changed files with 1196 additions and 217 deletions
+22 -21
View File
@@ -21,24 +21,6 @@ Show the gallery title and group photos by month:
}
```
## `singleImage`
**Type:** `bool` · **Default:** `false`
By default a link to a single image will directly open the image file. Set to `true` if you want to show a gallery page instead for a single item.
## `singleVideo`
**Type:** `bool` · **Default:** `true`
When a share contains a single video, show a gallery page. Set to `false` to link directly to the video file instead.
## `singleItemAutoOpen`
**Type:** `bool` · **Default:** `true`
When a share contains a single item and is opened on its gallery page, automatically open the lightbox on the asset.
## `showTitle`
**Type:** `bool` · **Default:** `true`
@@ -69,6 +51,12 @@ Format for the [`showExpiryDate`](#showexpirydate) date, as a [dayjs format stri
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.
## `showDownloadZip`
**Type:** `bool` · **Default:** `true`
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)).
## `groupByDate`
**Type:** `bool` or `string` · **Default:** `false`
@@ -76,16 +64,29 @@ Language for the [`showExpiryDate`](#showexpirydate) date when the format uses n
Group the gallery's thumbnails by date, with a header above each group.
- `false` - no grouping (default).
- `"month"` - month headers like "December 2024". `true` means the same.
- `"month"` - month headers like "December 2024".
- `"day"` - day headers like "Wed, 25 Dec 2024" (matching Immich's own timeline format).
- `true` - the same as `"month"`.
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`
## `singleImage`
**Type:** `bool` · **Default:** `false`
By default a link to a single image will directly open the image file. Set to `true` if you want to show a gallery page instead for a single item.
## `singleVideo`
**Type:** `bool` · **Default:** `true`
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)).
When a share contains a single video, show a gallery page. Set to `false` to link directly to the video file instead.
## `singleItemAutoOpen`
**Type:** `bool` · **Default:** `true`
When a share contains a single item and is opened on its gallery page, automatically open the lightbox on the asset.
## `cacheTime`
+12
View File
@@ -0,0 +1,12 @@
---
aside: false
---
# Config generator
Set the options you want, then copy the result into a `config.json` file or your `CONFIG` variable. Only the
options you change are included. [Configuration](/config/) explains where the config goes.
<ClientOnly>
<ConfigGenerator />
</ClientOnly>
+52 -18
View File
@@ -1,40 +1,51 @@
# Configuration
> [!TIP]
> You can see all of the configurable options by [looking at the default config.json](https://github.com/alangrainger/immich-public-proxy/blob/main/app/config.json), and the upload service's in [its own config.json](https://github.com/alangrainger/immich-public-proxy/blob/main/upload-app/config.json). A description of each option is on the pages in this section.
IPP can run with no config at all. Every option has a default, and the defaults are the most private choice: downloads
are off and every metadata field is hidden until you turn it on. A config holds only the keys you change; anything
you leave out keeps its default.
Connection settings (the Immich URL, public URL, port and config file location) are
[environment variables](/config/environment-variables). Everything else is JSON config under `ipp.*`, grouped into:
## Start with the Config generator
- [General options](/config/ipp-options) - downloads, zoom quality, slug links, the upload link, response headers.
- [Gallery](/config/gallery) - how the gallery page is rendered.
- [Lightbox](/config/lightbox) - the PhotoSwipe image viewer.
- [Metadata](/config/metadata) - description / EXIF / location reveal controls.
- [Error responses](/config/error-responses) - customise what invalid requests return.
- [Upload service](/config/upload-service) - the optional container that lets visitors send photos back.
- [Renamed config keys](/config/upgrading) - old keys and their current names.
The [Config generator](/config/generator) is the place to build your config and the place to see what each option
does. It lists every option with a short description, grouped the same way as the pages in this section. Set the ones
you want to change, and it writes the config for you in either of the two forms below, holding only the keys that
differ from the defaults.
It also works the other way: paste the config you already have, and the form fills in from it. Keys that IPP no
longer reads are listed with their current names, so it is the quickest way to update a config after a major
version upgrade.
## 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 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.
There are two ways to supply the config. If both are present, `CONFIG` is used and the file is not read.
### Mount a file
Recommended for anything non-trivial. Make a copy of [config.json](https://github.com/alangrainger/immich-public-proxy/blob/main/app/config.json) next to your `docker-compose.yml`, edit it, then add a volume:
Recommended for anything non-trivial. Put a `config.json` next to your `docker-compose.yml` holding only the keys
you change, then mount it into the container:
```yaml
volumes:
- ./config.json:/app/config.json
```
Restart the container and your custom configuration becomes active.
```json
{
"ipp": {
"allowDownload": 1,
"gallery": {
"showTitle": false
}
}
}
```
Restart the container and the config is active. To keep the file somewhere other than `/app/config.json`, set
[`IPP_CONFIG`](/config/environment-variables#ipp-config) to its path instead of mounting over the default.
### Inline via env var
For one-off or single-key overrides, pass the configuration inline from your `docker-compose.yml` using the `CONFIG` environment variable:
For one or two keys, pass the JSON in the `CONFIG` environment variable instead of a file:
```yaml
environment:
@@ -47,3 +58,26 @@ For one-off or single-key overrides, pass the configuration inline from your `do
}
}
```
The upload service reads config the same way, so one `config.json` or `CONFIG` value can be shared by both
containers.
## Full descriptions
The generator shows each option's summary. The pages below hold the full description of every key, with the
details and worked examples that don't fit beside a form field. Each page covers one group of keys and links to it
from the generator's "Details" links.
- [Environment variables](/config/environment-variables) - the Immich URL, public URL, port and config file location.
- [General options](/config/ipp-options) - `ipp.*`: downloads, zoom quality, slug links, the upload link, response headers.
- [Gallery](/config/gallery) - `ipp.gallery.*`: how the gallery page is rendered.
- [Lightbox](/config/lightbox) - `ipp.lightbox.*`: the image viewer.
- [Metadata](/config/metadata) - `ipp.showMetadata.*`: which description, EXIF and location fields visitors can see.
- [Error responses](/config/error-responses) - what an invalid request gets instead of a 404.
- [Upload service](/config/upload-service) - `ipp.upload.*`: the optional container that lets visitors send photos back.
- [Renamed config keys](/config/upgrading) - old key names and their current ones, for a config from an earlier
major version.
The defaults themselves are in
[`app/config.json`](https://github.com/alangrainger/immich-public-proxy/blob/main/app/config.json) and, for the upload
service, [`upload-app/config.json`](https://github.com/alangrainger/immich-public-proxy/blob/main/upload-app/config.json).
+81 -82
View File
@@ -19,24 +19,26 @@ Serve full-resolution images both when zooming in the lightbox and when download
}
```
## `responseHeaders`
## `allowDownload`
**Type:** `object`
**Type:** `int` · **Default:** `0`
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).
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).
```json
{
"ipp": {
"responseHeaders": {
"Cache-Control": "public, max-age=2592000",
"Access-Control-Allow-Origin": "*"
}
}
}
```
- `0` - downloads off.
- `1` - follow the Immich share's own download setting ([example](https://github.com/user-attachments/assets/79ea8c08-71ce-42ab-b025-10aec384938a)).
- `2` - always on.
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 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** 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 be sure every download works at full quality, leave the share's download permission on in Immich.
## `maxDownloadQuality`
@@ -48,6 +50,35 @@ Highest quality served for a download (the download button and "download all" zi
- `"fullsize"` - full resolution but always browser-displayable: the original for JPEG/PNG/WebP, Immich's converted full-size image for RAW/HEIF, in JPEG or WebP per the server's image settings.
- `"preview"` - only the ~1440px preview, in JPEG or WebP per the server's image settings.
## `downloadedFilename`
**Type:** `int` · **Default:** `2`
How downloaded files are named, both in the zip and for a single download. The extension always matches the bytes
served, so a preview download of a HEIC photo is `.jpg`.
- `0` - the original filename if available, falling back to the Immich asset ID.
- `1` - the Immich asset ID.
- `2` - an anonymous name made from the share and the item's position in it.
```
a3f9c2e1_001.jpg
a3f9c2e1_002.jpg
a3f9c2e1_003.mp4
```
With `2`, the same share always gives the same names, and a few selected items keep their positions in the whole
share. Unzipping a second download over the first replaces it. If the share's content or order changes, positions
shift, so a re-download then replaces files with different photos.
```json
{
"ipp": {
"downloadedFilename": 0
}
}
```
## `maxZoomQuality`
**Type:** `string` · **Default:** `"preview"`
@@ -77,73 +108,6 @@ Clips are only fetched while the toggle is on, so leaving this on costs no extra
}
```
## `downloadedFilename`
**Type:** `int` · **Default:** `2`
How downloaded files are named, both in the zip and for a single download. The extension always matches the bytes
served, so a preview download of a HEIC photo is `.jpg`.
- `0` - the original filename if available, falling back to the Immich asset ID.
- `1` - the Immich asset ID.
- `2` - an anonymous name made from the share and the item's position in it: the first 8 characters of a hash of
the share key, then the 1-based position in the order the gallery shows, zero-padded to at least three digits.
```
a3f9c2e1_001.jpg
a3f9c2e1_002.jpg
a3f9c2e1_003.mp4
```
With `2`, the same share always gives the same names, and a few selected items keep their positions in the whole
share. Unzipping a second download over the first replaces it. If the share's content or order changes, positions
shift, so a re-download then replaces files with different photos.
```json
{
"ipp": {
"downloadedFilename": 0
}
}
```
## `allowDownload`
**Type:** `int` · **Default:** `0`
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)).
- `2` - always on.
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 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** 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 be sure every download works at full quality, leave the share's download permission on in Immich.
## `uploadUrl`
**Type:** `string` · **Default:** `"/upload"`
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.
- **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.
## `allowSlugLinks`
**Type:** `bool` · **Default:** `true`
Serve shared links that have a custom URL in Immich at `/s/<slug>` as well as `/share/<key>`. Set to `false` to return a 404 for slug links, so that only the key form works.
## `showHomePage`
**Type:** `bool` · **Default:** `true`
@@ -158,6 +122,22 @@ Set to `false` to remove the IPP shield page at `/` and at `/share`.
}
```
## `allowSlugLinks`
**Type:** `bool` · **Default:** `true`
Serve shared links that have a custom URL in Immich at `/s/<slug>` as well as `/share/<key>`. Set to `false` to return a 404 for slug links, so that only the key form works.
## `uploadUrl`
**Type:** `string` · **Default:** `"/upload"`
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.
- **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.
## `gallery`
**Type:** `object`
@@ -181,3 +161,22 @@ Description / EXIF / location reveal controls. See [Metadata](/config/metadata).
**Type:** `various` · **Default:** `false`
Send a custom response instead of the default 404. See [Error responses](/config/error-responses).
## `responseHeaders`
**Type:** `object`
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
{
"ipp": {
"responseHeaders": {
"Cache-Control": "public, max-age=2592000",
"Access-Control-Allow-Origin": "*"
}
}
}
```
+6 -6
View File
@@ -26,18 +26,18 @@ Hide the download button inside the lightbox even though zip downloads are other
Show the prev/next arrows on desktop. They appear when the user hovers the lightbox.
## `showDownload`
**Type:** `bool` · **Default:** `true`
Show a download button in the lightbox toolbar. Only takes effect when downloads are also allowed by [`allowDownload`](/config/ipp-options#allowdownload).
## `mobileArrows`
**Type:** `bool` · **Default:** `false`
Show prev/next arrows on mobile (screens under 640px wide). Off by default, as visitors swipe instead.
## `showDownload`
**Type:** `bool` · **Default:** `true`
Show a download button in the lightbox toolbar. Only takes effect when downloads are also allowed by [`allowDownload`](/config/ipp-options#allowdownload).
## `autoPlayVideos`
**Type:** `bool` · **Default:** `false`