diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4d5600c..4f9877a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -105,7 +105,7 @@ Required environment variables (set in `app/.env` or your shell):
To exercise the full gallery flow you need a real Immich instance you can hit, with at least one public share created. The README has the user-facing setup steps for spinning that up.
-Configuration overrides go in `app/config.json` or inline via env (see `docs/inline-configuration.md`). Always read config through `getConfigOption('ipp.path.to.key', defaultValue)` rather than reading the JSON directly.
+Configuration overrides go in `app/config.json` or inline via env (see `docs/config/index.md`). Always read config through `getConfigOption('ipp.path.to.key', defaultValue)` rather than reading the JSON directly.
## Build, lint, test
diff --git a/README.md b/README.md
index e09600e..d536930 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ Setup takes less than a minute, and you never need to touch it again as all of y
- [Installation](#installation)
- [How to use it](#how-to-use-it)
- [How it works](#how-it-works)
-- [Configuration](docs/configuration.md)
+- [Configuration](docs/config/index.md)
- [Troubleshooting](#troubleshooting)
- [Feature requests](#feature-requests)
@@ -134,7 +134,7 @@ All incoming data is validated and sanitised, and anything unexpected is simply
## Configuration
-See **[the configuration docs](docs/configuration.md)** for the full reference.
+See **[the configuration docs](docs/config/index.md)** for the full reference.
## Troubleshooting
diff --git a/app/src/stream/download.ts b/app/src/stream/download.ts
index b7f83c0..8f7be94 100644
--- a/app/src/stream/download.ts
+++ b/app/src/stream/download.ts
@@ -96,7 +96,7 @@ export async function downloadAssets (res: Response, share: SharedLink, assets:
const options: StagingOptions = {
stagingDir: await fs.mkdtemp(join(tmpdir(), STAGING_DIR_PREFIX)),
- concurrency: Math.max(1, getConfigOption('ipp.downloadFromImmichConcurrencyLimit', 8) as number),
+ concurrency: Math.max(1, getConfigOption('ipp.downloadFromImmichConcurrencyLimit', 20) as number),
maxAttempts: 3,
headerTimeoutMs: 20_000,
idleTimeoutMs: 20_000
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 59384ee..655c3af 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -18,24 +18,30 @@ export default defineConfig({
provider: 'local'
},
nav: [
- { text: 'Guide', link: '/getting-started' },
- { text: 'Configuration', link: '/configuration' },
+ { text: 'About', link: '/introduction' },
+ { text: 'Configuration', link: '/config/' },
{ text: 'Live demo', link: DEMO_URL }
],
sidebar: [
{
text: 'Getting started',
items: [
- { text: 'Introduction', link: '/' },
- { text: 'Installation & usage', link: '/getting-started' }
+ { text: 'Introduction', link: '/introduction' },
+ { text: 'Installation', link: '/installation' },
+ { text: 'How to use it', link: '/how-to-use' },
+ { text: 'Troubleshooting', link: '/troubleshooting' }
]
},
{
- text: 'Configuration',
+ text: 'Config options',
items: [
- { text: 'Configuration reference', link: '/configuration' },
- { text: 'Inline (docker-compose) config', link: '/inline-configuration' },
- { text: 'Customising web responses', link: '/custom-responses' }
+ { text: 'Overview', link: '/config/' },
+ { text: 'IPP options', link: '/config/ipp-options' },
+ { text: 'Gallery', link: '/config/gallery' },
+ { text: 'Lightbox', link: '/config/lightbox' },
+ { text: 'Metadata', link: '/config/metadata' },
+ { text: 'Error responses', link: '/config/error-responses' },
+ { text: 'Upgrading & migration', link: '/config/upgrading' }
]
},
{
@@ -55,8 +61,7 @@ export default defineConfig({
text: 'Edit this page on GitHub'
},
footer: {
- message: 'Released under the AGPL-3.0 licence.',
- copyright: 'Copyright © Alan Grainger'
+ message: 'Released under the AGPL-3.0 licence.'
}
}
})
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
new file mode 100644
index 0000000..c93b14f
--- /dev/null
+++ b/docs/.vitepress/theme/custom.css
@@ -0,0 +1,17 @@
+/* Landing-page hero tweaks for the screenshot-as-hero-image.
+ VitePress's default hero floats a square logo up-and-left; for a wide
+ screenshot we want it centred and vertically aligned with the hero text. */
+@media (min-width: 960px) {
+ .VPHero .container {
+ align-items: center;
+ }
+
+ .VPHero .image {
+ min-height: auto;
+ }
+
+ /* Remove the default up-and-left offset so the image sits centred. */
+ .VPHero .image-container {
+ transform: none;
+ }
+}
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
new file mode 100644
index 0000000..9669c49
--- /dev/null
+++ b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,68 @@
+import DefaultTheme from 'vitepress/theme'
+import { h } from 'vue'
+import screenshot from '../../screenshot.webp'
+import './custom.css'
+
+const DEMO_URL = 'https://immich-demo.note.sx/share/gJfs8l4LcJJrBUpjhMnDoKXFt1Tm5vKXPbXl8BgwPtLtEBCOOObqbQdV5i0oun5hZjQ'
+
+/**
+ * Extend the default theme to:
+ * - use the live-demo screenshot as the hero image (`home-hero-image`),
+ * absolutely centred within the hero image container so it lines up
+ * vertically with the hero text;
+ * - place the IPP shield logo below the feature grid (`home-features-after`).
+ */
+export default {
+ extends: DefaultTheme,
+ Layout () {
+ return h(DefaultTheme.Layout, null, {
+ 'home-hero-actions-after': () => h(
+ 'div',
+ { style: 'display: flex; gap: 8px; margin-top: 24px; flex-wrap: wrap;' },
+ [
+ h('a', { href: 'https://github.com/alangrainger/immich-public-proxy', target: '_blank', rel: 'noreferrer' }, [
+ h('img', {
+ src: 'https://badgen.net/github/stars/alangrainger/immich-public-proxy?scale=1.1',
+ alt: 'GitHub stars',
+ style: 'vertical-align: middle;'
+ })
+ ]),
+ h('a', { href: 'https://hub.docker.com/r/alangrainger/immich-public-proxy', target: '_blank', rel: 'noreferrer' }, [
+ h('img', {
+ src: 'https://badgen.net/docker/pulls/alangrainger/immich-public-proxy?icon=docker&label=docker%20pulls&color=green&scale=1.1',
+ alt: 'Docker pulls',
+ style: 'vertical-align: middle;'
+ })
+ ])
+ ]
+ ),
+ 'home-hero-image': () => h(
+ 'a',
+ {
+ href: DEMO_URL,
+ style: 'position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); display: block; width: 100%;'
+ },
+ [
+ h('img', {
+ src: screenshot,
+ alt: 'Immich Public Proxy gallery screenshot',
+ style: 'width: 100%; border-radius: 12px; box-shadow: 0 6px 24px rgba(0, 0, 0, 0.12);'
+ })
+ ]
+ ),
+ 'home-features-after': () => h(
+ 'div',
+ { style: 'display: flex; justify-content: center; margin: 4rem auto 2rem;' },
+ [
+ h('img', {
+ src: '/ipp.svg',
+ alt: 'Immich Public Proxy',
+ width: 200,
+ height: 200,
+ style: 'opacity: 0.85;'
+ })
+ ]
+ )
+ })
+ }
+}
diff --git a/docs/custom-responses.md b/docs/config/error-responses.md
similarity index 94%
rename from docs/custom-responses.md
rename to docs/config/error-responses.md
index ee385cb..4e8ed6d 100644
--- a/docs/custom-responses.md
+++ b/docs/config/error-responses.md
@@ -1,4 +1,4 @@
-# Customising your web responses
+# Error responses
To avoid giving information away about your server, IPP responds with a limited set of HTTP status codes:
@@ -8,7 +8,7 @@ To avoid giving information away about your server, IPP responds with a limited
| 401 | Invalid password provided for a password-protected share link. |
| 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](/configuration#ipp-options) for `customInvalidResponse`.
+Instead of sending the 404 code, you can customise that response by [changing the configuration option](/config/ipp-options#custominvalidresponse) for `customInvalidResponse`.
Possible options are:
diff --git a/docs/config/gallery.md b/docs/config/gallery.md
new file mode 100644
index 0000000..0488fa3
--- /dev/null
+++ b/docs/config/gallery.md
@@ -0,0 +1,93 @@
+# Gallery
+
+Options that control how the gallery page is rendered. Configured under `ipp.gallery`.
+
+## Example
+
+Show the gallery title and group photos by month:
+
+```json
+{
+ "ipp": {
+ "gallery": {
+ "showTitle": true,
+ "groupByDate": true
+ }
+ }
+}
+```
+
+## `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`
+
+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`
+
+**Type:** `bool` · **Default:** `false`
+
+Show the album description below the title. This only applies if it is an album which is being shared.
+
+## `showExpiryDate`
+
+**Type:** `bool` · **Default:** `false`
+
+Show the share's expiry date next to the item count in the subtitle, as `45 items · available until 2026-07-10`. Only appears when the share actually has an expiry set in Immich (shares set to "never" show nothing extra).
+
+## `expiryDateFormat`
+
+**Type:** `string` · **Default:** `"YYYY-MM-DD"`
+
+Format for the [`showExpiryDate`](#showexpirydate) date, as a [dayjs format string](https://day.js.org/docs/en/display/format). The default is ISO 8601 (e.g. `2026-07-10`). Example: `"D MMMM YYYY"` renders `10 July 2026`. Name-based tokens (`MMMM`, `dddd`, ...) render in English unless you also set [`expiryDateLocale`](#expirydatelocale).
+
+## `expiryDateLocale`
+
+**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.
+
+## `groupByDate`
+
+**Type:** `bool` or `string` · **Default:** `false`
+
+Group the gallery's thumbnails by date, with a header above each group.
+
+- `false` - no grouping (default).
+- `true` / `"month"` - month headers like "December 2024".
+- `"day"` - day headers like "25 December 2024".
+
+Grouping uses each photo's local "taken" date (matching Immich's own timeline), and sorts photos newest-first. 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).
+
+> [!IMPORTANT]
+> Requires **"Show metadata"** to be enabled on the share in Immich. When that's off, Immich strips creation dates from the assets it returns to IPP, so grouping won't work.
+
+## `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)).
+
+## `cacheTime`
+
+**Type:** `int`
+
+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.
diff --git a/docs/config/index.md b/docs/config/index.md
new file mode 100644
index 0000000..ee860db
--- /dev/null
+++ b/docs/config/index.md
@@ -0,0 +1,53 @@
+# 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). A description of each option is on the pages in this section.
+
+All options live under `ipp.*`, grouped into:
+
+- [IPP options](/config/ipp-options) - top-level proxy behaviour.
+- [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.
+
+## 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.
+
+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 it, 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, pass the configuration inline from your `docker-compose.yml` using the `CONFIG` environment variable:
+
+```yaml
+ environment:
+ PUBLIC_BASE_URL: https://your-proxy-url.com
+ IMMICH_URL: http://your-internal-immich-server:2283
+ CONFIG: |
+ {
+ "ipp": {
+ "showHomePage": false
+ }
+ }
+```
+
+## 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.
diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md
new file mode 100644
index 0000000..22ca756
--- /dev/null
+++ b/docs/config/ipp-options.md
@@ -0,0 +1,117 @@
+# IPP options
+
+Top-level options under `ipp.*`.
+
+## Example
+
+Serve full-resolution images both when zooming in the lightbox and when downloading:
+
+```json
+{
+ "ipp": {
+ "maxDownloadQuality": "fullsize",
+ "maxZoomQuality": "fullsize"
+ }
+}
+```
+
+## `responseHeaders`
+
+**Type:** `object`
+
+Change the headers sent with your web responses. By default there is `cache-control` and CORS added.
+
+## `maxDownloadQuality`
+
+**Type:** `string` · **Default:** `"original"`
+
+Highest quality served for a download (the download button and "download all" zip).
+
+- `"original"` - the full-resolution original file (default).
+- `"fullsize"` - full resolution but always browser-displayable: the original for JPEG/PNG/WebP, Immich's converted JPEG for RAW/HEIF.
+- `"preview"` - only the ~1440px preview JPEG.
+
+## `maxZoomQuality`
+
+**Type:** `string` · **Default:** `"preview"`
+
+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.
+
+`"original"` is intentionally not an option (it could be an unviewable RAW/DNG or a huge file).
+
+**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.
+
+## `downloadedFilename`
+
+**Type:** `int` · **Default:** `0`
+
+The filename of the downloaded image.
+
+- `0` - the original filename if available, falling back to the Immich asset ID.
+- `1` - the Immich asset ID number.
+- `2` - a shortened version of the asset ID: `img_` plus the first 8 characters of the asset ID.
+
+## `allowDownload`
+
+**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)).
+
+- `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).
+
+## `downloadFromImmichConcurrencyLimit`
+
+**Type:** `int` · **Default:** `20`
+
+Maximum number of assets IPP will fetch from your Immich server in parallel when building a "download all" zip. 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`
+
+**Type:** `bool`
+
+Enable/disable the custom URL links.
+
+## `showHomePage`
+
+**Type:** `bool`
+
+Set to `false` to remove the IPP shield page at `/` and at `/share`.
+
+```json
+{
+ "ipp": {
+ "showHomePage": false
+ }
+}
+```
+
+## `gallery`
+
+**Type:** `object`
+
+Gallery-page options. See [Gallery](/config/gallery).
+
+## `lightbox`
+
+**Type:** `object`
+
+Lightbox options. See [Lightbox](/config/lightbox).
+
+## `showMetadata`
+
+**Type:** `object`
+
+Description / EXIF / location reveal controls. See [Metadata](/config/metadata).
+
+## `customInvalidResponse`
+
+**Type:** various
+
+Send a custom response instead of the default 404. See [Error responses](/config/error-responses).
diff --git a/docs/config/lightbox.md b/docs/config/lightbox.md
new file mode 100644
index 0000000..872b5e8
--- /dev/null
+++ b/docs/config/lightbox.md
@@ -0,0 +1,47 @@
+# Lightbox
+
+The gallery's lightbox is powered by [PhotoSwipe](https://photoswipe.com/). Configured under `ipp.lightbox`.
+
+## Example
+
+Hide the download button inside the lightbox even though zip downloads are otherwise allowed:
+
+```json
+{
+ "ipp": {
+ "lightbox": {
+ "showDownload": false
+ }
+ }
+}
+```
+
+## `showArrows`
+
+**Type:** `bool` · **Default:** `true`
+
+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 (under 640px viewport). Off by default since swipe is the natural mobile navigation.
+
+## `autoPlayVideos`
+
+**Type:** `bool` · **Default:** `false`
+
+Automatically play videos when their slide opens or becomes active. If the browser blocks unmuted autoplay (e.g. when deep-linking straight to a video), playback falls back to muted.
+
+## `options`
+
+**Type:** `object`
+
+Custom [PhotoSwipe options](https://photoswipe.com/options/) to override defaults (e.g. `{"wheelToZoom": true}`).
diff --git a/docs/config/metadata.md b/docs/config/metadata.md
new file mode 100644
index 0000000..b285cb3
--- /dev/null
+++ b/docs/config/metadata.md
@@ -0,0 +1,108 @@
+# 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.
+
+## 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,
+ "make": true,
+ "model": true,
+ "lensModel": true,
+ "exposureTime": true,
+ "iso": true,
+ "fNumber": true,
+ "focalLength": true
+ },
+ "location": { "city": true, "state": true, "country": true }
+ }
+ }
+}
+```
+
+## Overview
+
+| Group | 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. 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.
+
+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. Note that with "Show metadata" off Immich also strips file creation dates from non-album shares, so [date grouping](/config/gallery#groupbydate) won't work for those shares.
+
+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 flag set to `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`. Every flag defaults to `false`.
+
+| Option | Type | Description |
+|--------------------|--------|-----------------------------------------------|
+| `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`. Every flag defaults to `false`, except `webLink` which defaults to `true`.
+
+| Option | Type | Description |
+|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `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 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,
+ "make": true,
+ "model": true,
+ "lensModel": true,
+ "exposureTime": true,
+ "iso": true,
+ "fNumber": true,
+ "focalLength": true
+ },
+ "location": { "city": true, "state": true, "country": true }
+ }
+ }
+}
+```
diff --git a/docs/config/upgrading.md b/docs/config/upgrading.md
new file mode 100644
index 0000000..83979b4
--- /dev/null
+++ b/docs/config/upgrading.md
@@ -0,0 +1,36 @@
+# Upgrading & migration
+
+A few config keys have been renamed across versions. Existing configs continue to work via backward-compatibility shims and a startup deprecation notice.
+
+## 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.
+
+## `showMetadata.{exif,location}.enabled` was removed (v2.3.1)
+
+Per-field flags are now the only gate, and all default to `false`. The shim preserves behaviour for legacy configs by rewriting them in memory at startup:
+
+- Legacy `enabled: true` defaults every unset per-field flag in the group to `true`, matching the old "everything visible" behaviour. Per-field flags you had explicitly set to `false` (the "all except X" pattern) are kept.
+- Legacy `enabled: false` clears any per-field flags that were `true`, matching the old "nothing visible" behaviour and stopping leftover documentation flags from the shipped 2.3 config from becoming live opt-ins.
+
+A deprecation notice is printed at startup. Update your `config.json` to the explicit per-field form to silence it.
+
+## `downloadOriginalPhoto` → `maxDownloadQuality` (v3.0)
+
+The boolean becomes the quality tier: `true` maps to `"original"`, `false` to `"preview"`. The shim will be removed in v4.0.
+
+## `allowDownloadAll` → `allowDownload` (v3.0)
+
+Renamed, same `0` / `1` / `2` values. The shim will be removed in v4.0.
diff --git a/docs/configuration.md b/docs/configuration.md
deleted file mode 100644
index 4848bba..0000000
--- a/docs/configuration.md
+++ /dev/null
@@ -1,251 +0,0 @@
-# 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). A description of each of these options is below.
-
-## 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. The defaults in IPP are always the most privacy-respecting option.
-
-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.
-
-### Or 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.*`. 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.
-
-## 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. |
-| `maxDownloadQuality` | `string` | Highest quality served for a download (the download button and "download all" zip).
`"original"` the full-resolution original file (default)
`"fullsize"` full resolution but always browser-displayable - the original for JPEG/PNG/WebP, Immich's converted JPEG for RAW/HEIF
`"preview"` only the ~1440px preview JPEG. |
-| `maxZoomQuality` | `string` | 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. `"original"` is intentionally not an option (it could be an unviewable RAW/DNG or a huge file).
**Independent of `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` to control whether the download buttons appear. |
-| `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 |
-| `allowDownload` | `int` | 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` / `maxDownloadQuality`).
`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` and `lightbox.showDownload`. |
-| `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. |
-| `singleVideo` | `bool` | When a share contains a single video, show a gallery page (Default `true`). Set to `false` to link directly to the video file instead. |
-| `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. |
-| `showExpiryDate` | `bool` | Show the share's expiry date next to the item count in the subtitle, as `45 items · available until 2026-07-10`. Only appears when the share actually has an expiry set in Immich (shares set to "never" show nothing extra). Default `false`. |
-| `expiryDateFormat` | `string` | Format for the `showExpiryDate` date, as a [dayjs format string](https://day.js.org/docs/en/display/format). Default `"YYYY-MM-DD"` (ISO 8601 date, e.g. `2026-07-10`). Example: `"D MMMM YYYY"` renders `10 July 2026`. Name-based tokens (`MMMM`, `dddd`, ...) render in English unless you also set `expiryDateLocale`. |
-| `expiryDateLocale` | `string` | Locale for `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"`. Default `""` (dayjs's default English). The numeric default format needs no locale. Applies only to this server-rendered date; thumbnail date-group headers (`groupByDate`) already follow each viewer's own browser locale. |
-| `groupByDate` | `bool` or `string` | Group the gallery's thumbnails by date, with a header above each group. Set to `false` (default, no grouping), `true` / `"month"` for month headers like "December 2024", or `"day"` for day headers like "25 December 2024". Grouping uses each photo's local "taken" date (matching Immich's own timeline), and sorts photos newest-first. 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). **Requires "Show metadata" to be enabled on the share in Immich** - when that's off, Immich strips creation dates from the assets it returns to IPP, so grouping won't work. |
-| `showDownloadZip` | `bool` | 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`. Set to `false` to hide the zip download while still offering per-asset downloads via the lightbox (`lightbox.showDownload`). Default `true`. |
-| `cacheTime` | `int` | 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. |
-
-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 `allowDownload`. Default `true`. |
-| `mobileArrows` | `bool` | Show prev/next arrows on mobile (under 640px viewport). Off by default since swipe is the natural mobile navigation. |
-| `autoPlayVideos` | `bool` | Automatically play videos when their slide opens or becomes active. If the browser blocks unmuted autoplay (e.g. when deep-linking straight to a video), playback falls back to muted. Default `false`. |
-| `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. 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.
-
-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. Note that with "Show metadata" off Immich also strips file creation
-dates from non-album shares, so [date grouping](#gallery) won't work for those shares.
-
-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 flag set to `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 |
-|---------------------|--------|--------------------------------------------------------------------------|
-| `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 |
-|------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `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 camera EXIF, and revealing place names but not the GPS coordinates:
-
-```json
-{
- "ipp": {
- "showMetadata": {
- "description": { "caption": false, "sidebar": true },
- "exif": {
- "dateTimeOriginal": true,
- "make": true,
- "model": true,
- "lensModel": true,
- "exposureTime": true,
- "iso": true,
- "fNumber": true,
- "focalLength": true
- },
- "location": { "city": true, "state": true, "country": true }
- }
- }
-}
-```
-
-## 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.
-
-**`showMetadata.{exif,location}.enabled` was removed (v2.3.1).** Per-field flags are now the only gate, and all default to `false`. The shim preserves behaviour for legacy configs by rewriting them in memory at startup:
-
-- Legacy `enabled: true` defaults every unset per-field flag in the group to `true`, matching the old "everything visible" behaviour. Per-field flags you had explicitly set to `false` (the "all except X" pattern) are kept.
-- Legacy `enabled: false` clears any per-field flags that were `true`, matching the old "nothing visible" behaviour and stopping leftover documentation flags from the shipped 2.3 config from becoming live opt-ins.
-
-A deprecation notice is printed at startup. Update your `config.json` to the explicit per-field form to silence it. The shim will be removed in v3.0, and at that point any field IPP has added since v2.3 will need a fresh opt-in.
-
-**`downloadOriginalPhoto` -> `maxDownloadQuality` (v3.0).** The boolean becomes the quality tier: `true` maps to `"original"`, `false` to `"preview"`. The shim will be removed in v4.0.
-
-**`allowDownloadAll` -> `allowDownload` (v3.0).** Renamed, same `0` / `1` / `2` values. The shim will be removed in v4.0.
diff --git a/docs/getting-started.md b/docs/getting-started.md
deleted file mode 100644
index ed09254..0000000
--- a/docs/getting-started.md
+++ /dev/null
@@ -1,174 +0,0 @@
-# Getting started
-
-[Immich](https://github.com/immich-app/immich) is a wonderful bit of software, but since it holds all your private
-photos it's best to keep it fully locked down. This presents a problem when you want to share a photo or a gallery
-with someone.
-
-**Immich Public Proxy** provides a barrier of security between the public and Immich, and _only_ allows through
-requests which you have publicly shared.
-
-It is stateless and does not know anything about your Immich instance. It does not require an API key which reduces
-the attack surface even further. The only things that the proxy can access are photos that you have made publicly
-available in Immich.
-
-## Installation
-
-### Install with Docker / Podman
-
-1. Download the [docker-compose.yml](https://github.com/alangrainger/immich-public-proxy/blob/main/docker-compose.yml)
- file.
-
-2. Update the value for `IMMICH_URL` in your docker-compose file to point to your local URL for Immich. This should
- not be a public URL.
-
-3. Update or remove the value for `PUBLIC_BASE_URL`. This should be the public base URL for IPP, without a trailing
- 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. _Optional_: Add `IPP_PORT` to environment variables in your docker-compose file to change the port from the
- default of 3000. This is the _internal_ webserver port inside the container. Most people will not need to do this.
- Note that you will have to change the `ports` and `healthcheck` sections accordingly.
-
-5. 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.
-
-```bash
-docker-compose up -d
-```
-
-6. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve
- Immich Public Proxy:
-
-
-
-Now whenever you share an image or gallery through Immich, it will automatically create the correct public path for
-you.
-
-> [!WARNING]
-> If you're using Cloudflare, please make sure to set your `/share/video/*` path to Bypass Cache, otherwise you may
-> run into video playback issues. See [Troubleshooting](#troubleshooting) for more information.
-
-#### Running alongside Immich on a single domain
-
-Because all IPP paths are under `/share/...`, you can run Immich Public Proxy and Immich on the same domain. See
-[Running on a single domain](/running-on-single-domain).
-
-### Install with Kubernetes
-
-See the [Kubernetes install docs](/kubernetes).
-
-## How to use it
-
-Other than the initial configuration above, everything else is managed through Immich.
-
-You share your photos/videos as normal through Immich. Because you have set the **External domain** in Immich settings
-to be the URL for your proxy app, the links that Immich generates will automatically have the correct URL:
-
-
-
-## How it works
-
-When the proxy receives a request, it will come as a link like this:
-
-```
-https://your-proxy-url.com/share/ffSw63qnIYMtpmg0RNvOui0Dpio7BbxsObjvH8YZaobIjIAzl5n7zTX5d6EDHdOYEvo
-```
-
-The part after `/share/` is Immich's shared link public ID (called the `key`
-[in the docs](https://immich.app/docs/api/get-my-shared-link)).
-
-**Immich Public Proxy** takes that key and makes an API call to your Immich instance over your local network, to ask
-what photos or videos are shared in that share URL.
-
-If it is a valid share URL, the proxy fetches just those assets via local API and returns them to the visitor as an
-individual image or gallery.
-
-If the shared link has expired or any of the assets have been put in the Immich trash, it will not return those.
-
-All incoming data is validated and sanitised, and anything unexpected is simply dropped with a 404.
-
-## Configuration
-
-See the **[configuration reference](/configuration)** for the full list of options.
-
-## Troubleshooting
-
-### Video playback
-
-If you're using Cloudflare and having issues with videos not playing well, make sure your `/share/video/` paths are
-set to bypass cache. I ran into this issue myself, and found
-[some helpful advice here](https://community.cloudflare.com/t/mp4-wont-load-in-safari-using-cloudflare/10587/48).
-
-
-
-I use Linux/Android, so this project is tested with BrowserStack for Apple/Windows devices.
-
-### Can't reach Immich using `localhost:2283`
-
-This is a normal Docker thing, nothing to do with IPP.
-
-From inside a Docker container, you can't reach another container using `localhost`. You need to use a Docker network
-IP or your server's IP address.
-
-[Here's a guide on connecting Docker containers](https://dionarodrigues.dev/blog/docker-networking-how-to-connect-different-containers).
-
-### IPP logs "Unable to reach Immich", but `curl` inside the container works
-
-If IPP can't connect to Immich even though the container clearly can, you'll see this in the logs:
-
-```
-Unable to reach Immich on http://immich_server:2283
-From the server IPP is running on, see if you can curl to http://immich_server:2283/api/server/ping and receive a JSON result.
-```
-
-yet running that same `curl` from a shell inside the container succeeds:
-
-```
-/app $ curl http://immich_server:2283/api/server/ping
-{"res":"pong"}
-```
-
-This happens with both Docker Compose service names (like `immich_server`) and hostnames from a local DNS resolver
-(for example an AdGuard Home or dnsmasq CNAME rewrite). It is a quirk of the musl libc used by the `node:alpine` base
-image, not IPP itself.
-
-Node's `fetch` asks for the IPv4 (A) and IPv6 (AAAA) records at once. If your resolver answers the AAAA query with
-`NXDOMAIN` instead of the correct empty `NOERROR`, musl fails the whole lookup - even though the IPv4 address is valid
-- and IPP reports the connection as failed. `curl` and glibc (the non-alpine `node` image) tolerate this, which is why
-curl works and this only shows up here. The underlying error, hidden behind the log message above, is
-`getaddrinfo ENOTFOUND`.
-
-The reliable fix is to disable IPv6 for the container so only the IPv4 lookup happens. Add the `sysctls` block to your
-service in `docker-compose.yml`:
-
-```yaml
-services:
- immich-public-proxy:
- image: alangrainger/immich-public-proxy:latest
- # ...your existing config...
- sysctls:
- - net.ipv6.conf.all.disable_ipv6=1
- - net.ipv6.conf.default.disable_ipv6=1
-```
-
-Alternatively, point `IMMICH_URL` at Immich's IP address (a numeric address skips DNS resolution entirely), or fix
-your resolver to return an empty `NOERROR` (NODATA) rather than `NXDOMAIN` for the missing AAAA record.
-
-See issues [#203](https://github.com/alangrainger/immich-public-proxy/issues/203) and
-[#263](https://github.com/alangrainger/immich-public-proxy/issues/263) for the full investigation.
-
-## Feature requests
-
-You can [add feature requests here](https://github.com/alangrainger/immich-public-proxy/discussions/categories/feature-requests?discussions_q=is%3Aopen+category%3A%22Feature+Requests%22+sort%3Atop),
-however my goal with this project is to keep it as lean as possible.
-
-Due to the sensitivity of data contained within Immich, this project optimises for auditability: the code stays small
-enough that someone with coding experience can review it for security-relevant behavior.
-
-The most basic rule for this project is that it has **read-only** access to Immich.
-
-Things that will not be considered for this project are:
-
-- Anything that modifies Immich or its files in any way. If it requires an API key or privileged access, it won't be
- considered as a new feature.
-- Uploading photos (see above).
diff --git a/docs/how-to-use.md b/docs/how-to-use.md
new file mode 100644
index 0000000..904a2e1
--- /dev/null
+++ b/docs/how-to-use.md
@@ -0,0 +1,8 @@
+# How to use it
+
+Other than the initial configuration during [installation](/installation), everything else is managed through Immich.
+
+You share your photos/videos as normal through Immich. Because you have set the **External domain** in Immich settings
+to be the URL for your proxy app, the links that Immich generates will automatically have the correct URL:
+
+
diff --git a/docs/index.md b/docs/index.md
index 4fbf697..229d001 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,22 +5,16 @@ hero:
name: Immich Public Proxy
text: Share your photos safely
tagline: Share your Immich photos and albums publicly without exposing your Immich instance to the internet.
- image:
- src: /ipp.svg
- alt: Immich Public Proxy
actions:
- theme: brand
- text: Get started
- link: /getting-started
- - theme: alt
- text: Configuration
- link: /configuration
- - theme: alt
text: Live demo
link: https://immich-demo.note.sx/share/gJfs8l4LcJJrBUpjhMnDoKXFt1Tm5vKXPbXl8BgwPtLtEBCOOObqbQdV5i0oun5hZjQ
- theme: alt
- text: View on GitHub
- link: https://github.com/alangrainger/immich-public-proxy
+ text: Getting started
+ link: /introduction
+ - theme: alt
+ text: Configuration
+ link: /config/
features:
- title: Locked down by design
@@ -32,3 +26,4 @@ features:
- title: Managed entirely in Immich
details: All sharing stays managed within Immich itself. Set IPP up once and you never need to touch it again.
---
+
diff --git a/docs/inline-configuration.md b/docs/inline-configuration.md
deleted file mode 100644
index f63398b..0000000
--- a/docs/inline-configuration.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# `docker-compose` inline configuration
-
-Rather than a `config.json` file, you can pass the configuration inline from your `docker-compose.yml` file like this:
-
-```yaml
- environment:
- PUBLIC_BASE_URL: https://your-proxy-url.com
- IMMICH_URL: http://your-internal-immich-server:2283
- CONFIG: |
- {
- "ipp": {
- "singleImageGallery": false,
- ...
- }
- }
-```
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..38c37a1
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,41 @@
+# Installation
+
+## Install with Docker / Podman
+
+1. Download the [docker-compose.yml](https://github.com/alangrainger/immich-public-proxy/blob/main/docker-compose.yml)
+ file.
+
+2. Update the value for `IMMICH_URL` in your docker-compose file to point to your local URL for Immich. **This should
+ not be a public URL.** Most likely this will be a local IP and port; whatever your Immich container runs on.
+
+3. Update or remove the value for `PUBLIC_BASE_URL`. This should be the public base URL for IPP, without a trailing
+ 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.
+
+```bash
+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:
+
+
+
+Now whenever you share an image or gallery through Immich, it will automatically create the correct public path for
+you.
+
+> [!WARNING]
+> If you're using Cloudflare, please make sure to set your `/share/video/*` path to Bypass Cache, otherwise you may
+> run into video playback issues. See [Troubleshooting](#troubleshooting) for more information.
+
+### Running alongside Immich on a single domain
+
+Because all IPP paths are under `/share/...`, you can run Immich Public Proxy and Immich on the same domain. See
+[Running on a single domain](/running-on-single-domain).
+
+## Install with Kubernetes
+
+See the [Kubernetes install docs](/kubernetes).
diff --git a/docs/introduction.md b/docs/introduction.md
new file mode 100644
index 0000000..79609c8
--- /dev/null
+++ b/docs/introduction.md
@@ -0,0 +1,35 @@
+# Introduction
+
+[Immich](https://github.com/immich-app/immich) is a wonderful bit of software, but since it holds all your private
+photos it's best to keep it fully locked down. This presents a problem when you want to share a photo or a gallery
+with someone.
+
+**Immich Public Proxy** provides a barrier of security between the public and Immich, and _only_ allows through
+requests which you have publicly shared.
+
+It is stateless and does not know anything about your Immich instance. It does not require an API key which reduces
+the attack surface even further. The only things that the proxy can access are photos that you have made publicly
+available in Immich.
+
+## How it works
+
+When the proxy receives a request, it will come as a link like this:
+
+```
+https://your-proxy-url.com/share/ffSw63qnIYMtpmg0RNvOui0Dpio7BbxsObjvH8YZaobIjIAzl5n7zTX5d6EDHdOYEvo
+```
+
+The part after `/share/` is Immich's shared link public ID (called the `key`
+[in the docs](https://immich.app/docs/api/get-my-shared-link)).
+
+**Immich Public Proxy** takes that key and makes an API call to your Immich instance over your local network, to ask
+what photos or videos are shared in that share URL.
+
+If it is a valid share URL, the proxy fetches just those assets via local API and returns them to the visitor as an
+individual image or gallery.
+
+If the shared link has expired or any of the assets have been put in the Immich trash, it will not return those.
+
+All incoming data is validated and sanitised, and anything unexpected is simply dropped with a 404.
+
+Ready to set it up? Head to [Installation](/installation).
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..b16220c
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,65 @@
+# Troubleshooting
+
+## Video playback
+
+If you're using Cloudflare and having issues with videos not playing well, make sure your `/share/video/` paths are
+set to bypass cache. I ran into this issue myself, and found
+[some helpful advice here](https://community.cloudflare.com/t/mp4-wont-load-in-safari-using-cloudflare/10587/48).
+
+
+
+I use Linux/Android, so this project is tested with BrowserStack for Apple/Windows devices.
+
+## Can't reach Immich using `localhost:2283`
+
+This is a normal Docker thing, nothing to do with IPP.
+
+From inside a Docker container, you can't reach another container using `localhost`. You need to use a Docker network
+IP or your server's IP address.
+
+[Here's a guide on connecting Docker containers](https://dionarodrigues.dev/blog/docker-networking-how-to-connect-different-containers).
+
+## IPP logs "Unable to reach Immich", but `curl` inside the container works
+
+If IPP can't connect to Immich even though the container clearly can, you'll see this in the logs:
+
+```
+Unable to reach Immich on http://immich_server:2283
+From the server IPP is running on, see if you can curl to http://immich_server:2283/api/server/ping and receive a JSON result.
+```
+
+yet running that same `curl` from a shell inside the container succeeds:
+
+```
+/app $ curl http://immich_server:2283/api/server/ping
+{"res":"pong"}
+```
+
+This happens with both Docker Compose service names (like `immich_server`) and hostnames from a local DNS resolver
+(for example an AdGuard Home or dnsmasq CNAME rewrite). It is a quirk of the musl libc used by the `node:alpine` base
+image, not IPP itself.
+
+Node's `fetch` asks for the IPv4 (A) and IPv6 (AAAA) records at once. If your resolver answers the AAAA query with
+`NXDOMAIN` instead of the correct empty `NOERROR`, musl fails the whole lookup - even though the IPv4 address is valid
+- and IPP reports the connection as failed. `curl` and glibc (the non-alpine `node` image) tolerate this, which is why
+curl works and this only shows up here. The underlying error, hidden behind the log message above, is
+`getaddrinfo ENOTFOUND`.
+
+The reliable fix is to disable IPv6 for the container so only the IPv4 lookup happens. Add the `sysctls` block to your
+service in `docker-compose.yml`:
+
+```yaml
+services:
+ immich-public-proxy:
+ image: alangrainger/immich-public-proxy:latest
+ # ...your existing config...
+ sysctls:
+ - net.ipv6.conf.all.disable_ipv6=1
+ - net.ipv6.conf.default.disable_ipv6=1
+```
+
+Alternatively, point `IMMICH_URL` at Immich's IP address (a numeric address skips DNS resolution entirely), or fix
+your resolver to return an empty `NOERROR` (NODATA) rather than `NXDOMAIN` for the missing AAAA record.
+
+See issues [#203](https://github.com/alangrainger/immich-public-proxy/issues/203) and
+[#263](https://github.com/alangrainger/immich-public-proxy/issues/263) for the full investigation.