Update docs

This commit is contained in:
Alan Grainger
2026-09-04 12:55:08 +12:00
parent 18284ef5c5
commit ff45919107
24 changed files with 349 additions and 209 deletions
+51
View File
@@ -0,0 +1,51 @@
# Environment variables
Connection and runtime settings are passed as environment variables, typically in the `environment` section of your
`docker-compose.yml`. Only `IMMICH_URL` is required. Everything that controls how shares look and behave is JSON
config instead; see the [Configuration overview](/config/).
## `IMMICH_URL`
**Required**
The URL of your Immich server as reached from inside the IPP container, for example `http://immich_server:2283`.
Use the local address, not your public one: IPP is the only thing that needs to be public. A trailing slash is
ignored.
From inside a container, `localhost` does not reach Immich. If IPP logs "Unable to reach Immich" at startup, see
[Troubleshooting](/troubleshooting).
## `PUBLIC_BASE_URL`
**Optional** · **Default:** derived from each request
The public base URL of IPP without a trailing slash, for example `https://your-proxy-url.com`. The gallery uses
relative URLs everywhere except the `og:image` tag that messaging apps read for link previews, which must be fully
qualified. When unset, IPP builds it from the incoming request's protocol and `Host` header.
Set it if link previews show `http://` or a private address. Leave it unset if you serve IPP from several domains,
and make sure your reverse proxy forwards the original `Host` header.
## `IPP_PORT`
**Optional** · **Default:** `3000`
The port the web server listens on inside the container. If you change it, update the `ports` mapping and the
`healthcheck` in your compose file to match.
## `IPP_CONFIG`
**Optional** · **Default:** `/app/config.json`
Path to the JSON config file, either absolute or relative to the working directory. Use it to keep the config
somewhere other than the default path. The usual approach is to mount your file over the default path instead, as
described in the [Configuration overview](/config/#mount-a-file).
## `CONFIG`
**Optional**
The JSON config as an inline string. When set, no config file is read at all. See
[Inline via env var](/config/#inline-via-env-var) for an example.
`APP_VERSION` and `NODE_ENV` are set by the Docker image and are not meant to be changed.
+1 -1
View File
@@ -85,6 +85,6 @@ Show the bulk-zip download UI - the "download all" button in the header and the
## `cacheTime`
**Type:** `int`
**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.
+6 -11
View File
@@ -3,21 +3,22 @@
> [!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). A description of each option is on the pages in this section.
All options live under `ipp.*`, grouped into:
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:
- [IPP options](/config/ipp-options) - top-level proxy behaviour.
- [General options](/config/ipp-options) - downloads, zoom quality, slug links, 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.
- [Upgrading & migration](/config/upgrading) - renamed keys and compatibility shims.
- [Legacy config keys](/config/upgrading) - renamed keys and compatibility shims.
## How to provide a config override
> [!NOTE]
> You only need to include the keys you're changing. Anything you omit keeps its default. The defaults in IPP are always the most privacy-respecting option.
> 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.
There are two ways to supply custom config.
There are two ways to supply custom config. If both are present, `CONFIG` wins and the file is not read.
### Mount a file
@@ -45,9 +46,3 @@ For one-off or single-key overrides, pass the configuration inline from your `do
}
}
```
## How options are organised
All options live under `ipp.*`. The metadata groups (`ipp.showMetadata.exif`, `ipp.showMetadata.location`) are per-field opt-in: every field is off until you explicitly set its flag to `true`. Nothing is automatically exposed - including fields IPP adds in future versions.
You only need to include the keys you're changing. Anything you omit keeps its default.
+17 -6
View File
@@ -1,6 +1,6 @@
# IPP options
# General options
Top-level options under `ipp.*`.
Top-level options under `ipp.*` that don't belong to the [Gallery](/config/gallery), [Lightbox](/config/lightbox) or [Metadata](/config/metadata) groups.
## Example
@@ -19,7 +19,18 @@ Serve full-resolution images both when zooming in the lightbox and when download
**Type:** `object`
Change the headers sent with your web responses. By default there is `cache-control` and CORS added.
Change the headers sent with your web responses. The default is a 30-day `Cache-Control` and a permissive CORS header:
```json
{
"ipp": {
"responseHeaders": {
"Cache-Control": "public, max-age=2592000",
"Access-Control-Allow-Origin": "*"
}
}
}
```
## `maxDownloadQuality`
@@ -77,13 +88,13 @@ The bulk-zip and per-asset buttons can be toggled independently once downloads a
## `allowSlugLinks`
**Type:** `bool`
**Type:** `bool` · **Default:** `true`
Enable/disable the custom URL links.
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`
**Type:** `bool` · **Default:** `true`
Set to `false` to remove the IPP shield page at `/` and at `/share`.
-26
View File
@@ -83,29 +83,3 @@ Under `ipp.showMetadata.location`. Every flag defaults to `false`, except `webLi
| `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`. |
## Example
Show the description in the sidebar only (not as a lightbox caption), expose camera EXIF, and reveal place names but not the GPS coordinates:
```json
{
"ipp": {
"showMetadata": {
"description": { "caption": false, "sidebar": true },
"exif": {
"dateTimeOriginal": true,
"timeZone": true,
"make": true,
"model": true,
"lensModel": true,
"exposureTime": true,
"iso": true,
"fNumber": true,
"focalLength": true
},
"location": { "city": true, "state": true, "country": true }
}
}
}
```
+2 -2
View File
@@ -1,6 +1,6 @@
# Upgrading & migration
# Legacy config keys
A few config keys have been renamed across versions. Existing configs continue to work via backward-compatibility shims and a startup deprecation notice.
A few config keys have been renamed or reshaped across versions. Old configs keep working through backward-compatibility shims, with a deprecation notice logged at startup; update to the current names to silence it. For how to update IPP itself, see [Upgrading](/upgrading).
## Gallery keys moved under `ipp.gallery.*` (v2.0)