This commit is contained in:
Alan Grainger
2026-07-24 11:58:29 +12:00
parent cd69bbd877
commit 6b0b193961
21 changed files with 715 additions and 468 deletions
+1 -1
View File
@@ -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
+2 -2
View File
@@ -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
+1 -1
View File
@@ -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
+15 -10
View File
@@ -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.'
}
}
})
+17
View File
@@ -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;
}
}
+68
View File
@@ -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;'
})
]
)
})
}
}
@@ -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:
+93
View File
@@ -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.
+53
View File
@@ -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.
+117
View File
@@ -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).
+47
View File
@@ -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}`).
+108
View File
@@ -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 }
}
}
}
```
+36
View File
@@ -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.
-251
View File
@@ -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).<br>`"original"` the full-resolution original file (default)<br>`"fullsize"` full resolution but always browser-displayable - the original for JPEG/PNG/WebP, Immich's converted JPEG for RAW/HEIF<br>`"preview"` only the ~1440px preview JPEG. |
| `maxZoomQuality` | `string` | Highest quality the lightbox loads when you zoom in past fit-to-screen.<br>`"preview"` keep the preview (default; zoom is capped to the preview's real pixels)<br>`"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).<br>**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.<br>`0` for the original filename if available, falling back to the Immich asset ID<br>`1` for the Immich asset ID number<br>`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`).<br>`0` downloads off<br>`1` follow the Immich share's own download setting ([example](https://github.com/user-attachments/assets/79ea8c08-71ce-42ab-b025-10aec384938a))<br>`2` always on.<br>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.
-174
View File
@@ -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:
<img src="/server-settings.png" width="400" height="182" alt="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:
<img src="/share-link.webp" width="751" height="524" alt="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).
<a href="/cloudflare-video-cache.webp"><img src="/cloudflare-video-cache.webp" style="width:70%" alt="Cloudflare cache bypass rule for video paths"></a>
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).
+8
View File
@@ -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:
<img src="/share-link.webp" width="751" height="524" alt="Sharing a link from Immich">
+6 -11
View File
@@ -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.
---
-16
View File
@@ -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,
...
}
}
```
+41
View File
@@ -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:
<img src="/server-settings.png" width="400" height="182" alt="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).
+35
View File
@@ -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).
+65
View File
@@ -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).
<a href="/cloudflare-video-cache.webp"><img src="/cloudflare-video-cache.webp" style="width:70%" alt="Cloudflare cache bypass rule for video paths"></a>
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.