diff --git a/README.md b/README.md index f97f28b..5751775 100644 --- a/README.md +++ b/README.md @@ -27,17 +27,9 @@ Setup takes less than a minute, and you never need to touch it again as all of y - [About this project](#about-this-project) - [Installation](#installation) - - [Install with Docker](#install-with-docker--podman) - - [Install with Kubernetes](docs/kubernetes.md) - [How to use it](#how-to-use-it) - [How it works](#how-it-works) -- [Additional configuration](#additional-configuration) - - [IPP options](#immich-public-proxy-options) - - [Gallery options](#gallery-options) - - [Lightbox options](#lightbox-options) - - [Metadata](#metadata) - - [Custom error pages](#customising-your-error-response-pages) - - [Serving from multiple domains](#serving-from-multiple-domains) +- [Configuration](docs/configuration.md) - [Troubleshooting](#troubleshooting) - [Feature requests](#feature-requests) @@ -92,7 +84,7 @@ Check the container console output for any error messages. docker-compose up -d ``` -5. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve Immich Public Proxy: +6. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve Immich Public Proxy: @@ -140,184 +132,9 @@ If the shared link has expired or any of the assets have been put in the Immich All incoming data is validated and sanitised, and anything unexpected is simply dropped with a 404. -## Additional configuration +## Configuration -There are some additional configuration options you can change, for example the way the gallery is set up. - -1. Make a copy of [config.json](https://github.com/alangrainger/immich-public-proxy/blob/main/app/config.json) in the same folder as your `docker-compose.yml`. - -2. Pass the config to your docker container by adding a volume like this: - -```yaml - volumes: - - ./config.json:/app/config.json -``` - -3. Restart your container and your custom configuration should be active. - -Alternatively, you can [pass the configuration inline](docs/inline-configuration.md) from your `docker-compose.yml` file. - -### Immich Public Proxy options - -| Option | Type | Description | -|---------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `responseHeaders` | `object` | Change the headers sent with your web responses. By default there is `cache-control` and CORS added. | -| `downloadOriginalPhoto` | `bool` | Set to `false` if you only want people to be able to download the 'preview' quality photo, rather than your original photo. | -| `downloadedFilename` | `int` | The filename of the downloaded image.
`0` for the original filename if available, falling back to the Immich asset ID
`1` for the Immich asset ID number
`2` for a shortened version of the asset ID: `img_` plus the first 8 characters of the asset ID | -| `allowDownloadAll` | `int` | Allow visitors to download all files as a zip, including the selective-download flow in multi-select mode.
`0` disable downloads
`1` follow Immich setting per share ([example](https://github.com/user-attachments/assets/79ea8c08-71ce-42ab-b025-10aec384938a))
`2` always allowed | -| `downloadFromImmichConcurrencyLimit` | `int` | Maximum number of assets IPP will fetch from your Immich server in parallel when building a "download all" zip. Defaults to `8`. Lower this if your Immich server is slow or you see download timeouts on large albums; raise it for faster downloads if your server can handle the load. | -| `allowSlugLinks` | `bool` | Enable/disable the custom URL links. | -| `showHomePage` | `bool` | Set to `false` to remove the IPP shield page at `/` and at `/share` | -| `gallery` | `object` | Gallery-page options, see the [Gallery options](#gallery-options) section below. | -| `lightbox` | `object` | Lightbox option, see the [Lightbox options](#lightbox-options) section below. | -| `showMetadata` | `object` | See the [Metadata](#metadata) section below. | -| `customInvalidResponse` | various | Send a custom response instead of the default 404 - see [Custom responses](docs/custom-responses.md) for more details. | - -For example, to disable the home page at `/` and at `/share` you need to change `showHomePage` to `false`: - -```json -{ - "ipp": { - "showHomePage": false, - ... - } -} -``` - -### Gallery options - -Options that control how the gallery page is rendered. Configured under `ipp.gallery`. - -| Option | Type | Description | -|----------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `singleImage` | `bool` | 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. | -| `singleItemAutoOpen` | `bool` | When a share contains a single item and is opened on its gallery page, automatically open the lightbox on the asset. Default `true`. | -| `showTitle` | `bool` | Show a title on the gallery page. This is taken from the album title if it is an album being shared, otherwise the "Description" from the shared link will be used. | -| `showDescription` | `bool` | Show the album description below the title. This only applies if it is an album which is being shared. | -| `groupByDate` | `bool` | Group the gallery's thumbnails by month, with headers like "December 2024" above each group. Sorts photos newest-first. Items missing a creation date end up under an "Undated" bucket at the end. Default `false`. | - -Example: show the gallery title and group photos by month: - -```json -{ - "ipp": { - "gallery": { - "showTitle": true, - "groupByDate": true - } - } -} -``` - -> **Note** for upgraders from earlier versions: the keys `singleImageGallery`, `singleItemAutoOpen`, `showGalleryTitle`, `showGalleryDescription`, and `groupGalleryByDate` used to live directly under `ipp.*`. They've been renamed and moved under `ipp.gallery.*` (see the table above). Existing configs continue to work via a backward-compatibility shim, but you'll see a deprecation notice in the startup log until you migrate them. - -### Lightbox options - -The gallery's lightbox is powered by [PhotoSwipe](https://photoswipe.com/). Configured under `ipp.lightbox`. - -| Option | Type | Description | -|----------------|----------|------------------------------------------------------------------------------------------------------------------------------------------| -| `showArrows` | `bool` | Show the prev/next arrows on desktop. They appear when the user hovers the lightbox. Default `true`. | -| `showDownload` | `bool` | Show a download button in the lightbox toolbar. Only takes effect when downloads are also allowed by `allowDownloadAll`. Default `true`. | -| `mobileArrows` | `bool` | Show prev/next arrows on mobile (under 640px viewport). Off by default since swipe is the natural mobile navigation. | -| `options` | `object` | Custom [PhotoSwipe options](https://photoswipe.com/options/) to override defaults (e.g. `{"wheelToZoom": true}`). | - -Example: hide the download button inside the lightbox even though zip downloads are otherwise allowed: - -```json -{ - "ipp": { - "lightbox": { - "showDownload": false - } - } -} -``` - -### Metadata - -Configured under `ipp.showMetadata`. The lightbox includes a slide-in info sidebar (toggle with the **i** key or the info button in the toolbar) that surfaces whatever metadata you opt into here. - -| Option | Type | Description | -|---------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------| -| `description` | `object` | Where to show the description. `{ "caption": bool, "sidebar": bool }`. Both default `false`. See [Description](#description). | -| `exif` | `object` | Camera / file EXIF group. Set `enabled: true` to expose any of the per-field flags below. See [EXIF group](#exif-group). | -| `location` | `object` | Location group (city / state / country / GPS). Set `enabled: true` to expose any of the per-field flags below. See [Location group](#location-group). | - -Within each group, the master `enabled` toggle controls whether the group's fields are sent at all. Per-field flags default to `true` once the group is enabled, so you can turn off individual fields without renaming or removing them. - -IPP only sends a field if **both** the group's `enabled` is true AND the field's flag is true. If Immich itself isn't exposing metadata for the share (the per-share toggle on the Immich side), no metadata is available regardless of these settings. - -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`, `exif.enabled`, or `location.enabled` is true. With all three off, the sidebar UI is suppressed. - -#### Description - -Under `ipp.showMetadata.description`: - -| Option | Type | Description | -|-----------|--------|--------------------------------------------------------------------------| -| `caption` | `bool` | Show the description below the photo as a lightbox caption. | -| `sidebar` | `bool` | Show the description at the top of the info sidebar. | - -Set both to show in both places; set neither and the description is not included at all. (Legacy `description: true` / `description: false` boolean form is still accepted and migrates to `{caption, sidebar}` of the same value with a deprecation warning.) - -#### EXIF group - -Under `ipp.showMetadata.exif`: - -| Option | Type | Description | -|---------------------|--------|--------------------------------------------------------------------------| -| `enabled` | `bool` | Master switch for the EXIF group. Default `false`. | -| `dateTimeOriginal` | `bool` | Show the date the photo was taken (per EXIF). | -| `fileName` | `bool` | Show the original filename. | -| `dimensions` | `bool` | Show width x height and megapixel count. | -| `fileSize` | `bool` | Show the file size. | -| `make` | `bool` | Camera manufacturer (e.g. "Canon"). | -| `model` | `bool` | Camera model (e.g. "EOS R5"). | -| `lensModel` | `bool` | Lens model. | -| `exposureTime` | `bool` | Shutter speed (e.g. "1/200"). | -| `iso` | `bool` | ISO sensitivity. | -| `fNumber` | `bool` | Aperture f-number. | -| `focalLength` | `bool` | Focal length in millimetres. | - -#### Location group - -Under `ipp.showMetadata.location`: - -| Option | Type | Description | -|------------|--------|----------------------------------------------------------------------| -| `enabled` | `bool` | Master switch for the location group. Default `false`. | -| `city` | `bool` | Show city. | -| `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`. | - -Example: show description in the sidebar only (not as a caption), show full EXIF, and hide GPS coordinates while keeping city / state / country: - -```json -{ - "ipp": { - "showMetadata": { - "description": { "caption": false, "sidebar": true }, - "exif": { "enabled": true }, - "location": { "enabled": true, "gps": false } - } - } -} -``` - -### Customising your error response pages - -You can customise the responses that IPP sends for invalid requests. For example you could: - -- Drop the connection entirely (no response). -- Redirect to a new website. -- Send a different status code. -- Send a custom 404 page. -- And so on... - -See [Custom responses](docs/custom-responses.md) for more details. +See **[the configuration docs](docs/configuration.md)** for the full reference. ## Troubleshooting diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..720b84f --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,220 @@ +# Configuration + +Immich Public Proxy runs with sane defaults; most installs never need to touch `config.json`. Override only what you need. + +## Contents + +- [How to provide a config override](#how-to-provide-a-config-override) +- [How options are organised](#how-options-are-organised) +- [IPP options](#ipp-options) +- [Gallery](#gallery) +- [Lightbox](#lightbox) +- [Metadata](#metadata) + - [Description](#description) + - [EXIF group](#exif-group) + - [Location group](#location-group) +- [Customising your error response pages](#customising-your-error-response-pages) +- [Migration notes for upgraders](#migration-notes-for-upgraders) + +## How to provide a config override + +**Note:** You only need to include the keys you're changing. Anything you omit keeps its default. + +There are two ways to supply custom config: + +#### 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, then add a volume: + +```yaml + volumes: + - ./config.json:/app/config.json +``` + +Restart the container and your custom configuration becomes active. + +#### Inline via env var: + +For one-off or single-key overrides. See [inline configuration](inline-configuration.md). + +## How options are organised + +All options live under `ipp.*`. Several groups follow a master-toggle plus per-field-overrides pattern (`ipp.showMetadata.exif`, `ipp.showMetadata.location`): set the group's `enabled: true` to expose the group, then turn individual fields off if you want fewer. + +**You only need to include the keys you're changing. Anything you omit keeps its default.** + +## IPP options + +Top-level options under `ipp.*`. + +| Option | Type | Description | +|---------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `responseHeaders` | `object` | Change the headers sent with your web responses. By default there is `cache-control` and CORS added. | +| `downloadOriginalPhoto` | `bool` | Set to `false` if you only want people to be able to download the 'preview' quality photo, rather than your original photo. | +| `downloadedFilename` | `int` | The filename of the downloaded image.
`0` for the original filename if available, falling back to the Immich asset ID
`1` for the Immich asset ID number
`2` for a shortened version of the asset ID: `img_` plus the first 8 characters of the asset ID | +| `allowDownloadAll` | `int` | Allow visitors to download all files as a zip, including the selective-download flow in multi-select mode.
`0` disable downloads
`1` follow Immich setting per share ([example](https://github.com/user-attachments/assets/79ea8c08-71ce-42ab-b025-10aec384938a))
`2` always allowed | +| `downloadFromImmichConcurrencyLimit` | `int` | Maximum number of assets IPP will fetch from your Immich server in parallel when building a "download all" zip. Defaults to `8`. Lower this if your Immich server is slow or you see download timeouts on large albums; raise it for faster downloads if your server can handle the load. | +| `allowSlugLinks` | `bool` | Enable/disable the custom URL links. | +| `showHomePage` | `bool` | Set to `false` to remove the IPP shield page at `/` and at `/share`. | +| `gallery` | `object` | Gallery-page options. See [Gallery](#gallery). | +| `lightbox` | `object` | Lightbox options. See [Lightbox](#lightbox). | +| `showMetadata` | `object` | Description / EXIF / location reveal controls. See [Metadata](#metadata). | +| `customInvalidResponse` | various | Send a custom response instead of the default 404. See [Custom responses](custom-responses.md). | + +For example, to disable the home page at `/` and at `/share`: + +```json +{ + "ipp": { + "showHomePage": false + } +} +``` + +## Gallery + +Options that control how the gallery page is rendered. Configured under `ipp.gallery`. + +| Option | Type | Description | +|----------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `singleImage` | `bool` | 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. | +| `singleItemAutoOpen` | `bool` | When a share contains a single item and is opened on its gallery page, automatically open the lightbox on the asset. Default `true`. | +| `showTitle` | `bool` | Show a title on the gallery page. This is taken from the album title if it is an album being shared, otherwise the "Description" from the shared link will be used. | +| `showDescription` | `bool` | Show the album description below the title. This only applies if it is an album which is being shared. | +| `groupByDate` | `bool` | Group the gallery's thumbnails by month, with headers like "December 2024" above each group. Sorts photos newest-first. Items missing a creation date end up under an "Undated" bucket at the end. Default `false`. | + +Example: show the gallery title and group photos by month. + +```json +{ + "ipp": { + "gallery": { + "showTitle": true, + "groupByDate": true + } + } +} +``` + +## Lightbox + +The gallery's lightbox is powered by [PhotoSwipe](https://photoswipe.com/). Configured under `ipp.lightbox`. + +| Option | Type | Description | +|----------------|----------|------------------------------------------------------------------------------------------------------------------------------------------| +| `showArrows` | `bool` | Show the prev/next arrows on desktop. They appear when the user hovers the lightbox. Default `true`. | +| `showDownload` | `bool` | Show a download button in the lightbox toolbar. Only takes effect when downloads are also allowed by `allowDownloadAll`. Default `true`. | +| `mobileArrows` | `bool` | Show prev/next arrows on mobile (under 640px viewport). Off by default since swipe is the natural mobile navigation. | +| `options` | `object` | Custom [PhotoSwipe options](https://photoswipe.com/options/) to override defaults (e.g. `{"wheelToZoom": true}`). | + +Example: hide the download button inside the lightbox even though zip downloads are otherwise allowed. + +```json +{ + "ipp": { + "lightbox": { + "showDownload": false + } + } +} +``` + +## Metadata + +Configured under `ipp.showMetadata`. The lightbox includes a slide-in info sidebar (toggle with the **i** key or the info button in the toolbar) that surfaces whatever metadata you opt into here. + +| Option | Type | Description | +|---------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `description` | `object` | Where to show the description. `{ "caption": bool, "sidebar": bool }`. Both default `false`. See [Description](#description). | +| `exif` | `object` | Camera / file EXIF group. Set `enabled: true` to expose any of the per-field flags below. See [EXIF group](#exif-group). | +| `location` | `object` | Location group (city / state / country / GPS). Set `enabled: true` to expose any of the per-field flags below. See [Location group](#location-group). | + +Within each group, the master `enabled` toggle controls whether the group's fields are sent at all. Per-field flags default to `true` once the group is enabled, so you can turn off individual fields without renaming or removing them. + +IPP only sends a field if **both** the group's `enabled` is true AND the field's flag is true. If Immich itself isn't exposing metadata for the share (the per-share toggle on the Immich side), no metadata is available regardless of these settings. + +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`, `exif.enabled`, or `location.enabled` is true. With all three off, the sidebar UI is suppressed. + +### Description + +Under `ipp.showMetadata.description`. + +| Option | Type | Description | +|-----------|--------|--------------------------------------------------------------------------| +| `caption` | `bool` | Show the description below the photo as a lightbox caption. | +| `sidebar` | `bool` | Show the description at the top of the info sidebar. | + +Set both to show in both places; set neither and the description is not included at all. + +### EXIF group + +Under `ipp.showMetadata.exif`. + +| Option | Type | Description | +|---------------------|--------|--------------------------------------------------------------------------| +| `enabled` | `bool` | Master switch for the EXIF group. Default `false`. | +| `dateTimeOriginal` | `bool` | Show the date the photo was taken (per EXIF). | +| `fileName` | `bool` | Show the original filename. | +| `dimensions` | `bool` | Show width x height and megapixel count. | +| `fileSize` | `bool` | Show the file size. | +| `make` | `bool` | Camera manufacturer (e.g. "Canon"). | +| `model` | `bool` | Camera model (e.g. "EOS R5"). | +| `lensModel` | `bool` | Lens model. | +| `exposureTime` | `bool` | Shutter speed (e.g. "1/200"). | +| `iso` | `bool` | ISO sensitivity. | +| `fNumber` | `bool` | Aperture f-number. | +| `focalLength` | `bool` | Focal length in millimetres. | + +### Location group + +Under `ipp.showMetadata.location`. + +| Option | Type | Description | +|------------|--------|----------------------------------------------------------------------| +| `enabled` | `bool` | Master switch for the location group. Default `false`. | +| `city` | `bool` | Show city. | +| `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`. | + +A full example showing the description in the sidebar only (not as a lightbox caption), exposing full EXIF, and revealing place names but not the GPS coordinates: + +```json +{ + "ipp": { + "showMetadata": { + "description": { "caption": false, "sidebar": true }, + "exif": { "enabled": true }, + "location": { "enabled": true, "gps": false } + } + } +} +``` + +## Customising your error response pages + +You can customise the responses that IPP sends for invalid requests. For example you could: + +- Drop the connection entirely (no response). +- Redirect to a new website. +- Send a different status code. +- Send a custom 404 page. + +See [Custom responses](custom-responses.md) for the full reference. + +## Migration notes for upgraders + +A few config keys have been renamed across versions. Existing configs continue to work via backward-compatibility shims and a startup deprecation notice. The shims will be removed in v3.0. + +**Gallery keys moved under `ipp.gallery.*` (v2.0).** The old top-level keys are mapped automatically: + +| Legacy key | New key | +|---------------------------|-------------------------------| +| `ipp.singleImageGallery` | `ipp.gallery.singleImage` | +| `ipp.singleItemAutoOpen` | `ipp.gallery.singleItemAutoOpen` | +| `ipp.showGalleryTitle` | `ipp.gallery.showTitle` | +| `ipp.showGalleryDescription` | `ipp.gallery.showDescription` | +| `ipp.groupGalleryByDate` | `ipp.gallery.groupByDate` | + +**`showMetadata.description` is now an object.** It used to be a single boolean. A legacy `description: true` migrates to `{ caption: true, sidebar: true }` (and `false` to both `false`). Move to the explicit form to silence the deprecation notice and so you can target the caption vs. the sidebar independently.