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: - -Immich server settings - external domain - -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: - -Sharing a link from 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. - -## 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). - -Cloudflare cache bypass rule for video paths - -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: + +Sharing a link from Immich 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: + +Immich server settings - external domain + +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). + +Cloudflare cache bypass rule for video paths + +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.