Docs WIP
This commit is contained in:
+1
-1
@@ -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.
|
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
|
## Build, lint, test
|
||||||
|
|
||||||
|
|||||||
@@ -29,7 +29,7 @@ Setup takes less than a minute, and you never need to touch it again as all of y
|
|||||||
- [Installation](#installation)
|
- [Installation](#installation)
|
||||||
- [How to use it](#how-to-use-it)
|
- [How to use it](#how-to-use-it)
|
||||||
- [How it works](#how-it-works)
|
- [How it works](#how-it-works)
|
||||||
- [Configuration](docs/configuration.md)
|
- [Configuration](docs/config/index.md)
|
||||||
- [Troubleshooting](#troubleshooting)
|
- [Troubleshooting](#troubleshooting)
|
||||||
- [Feature requests](#feature-requests)
|
- [Feature requests](#feature-requests)
|
||||||
|
|
||||||
@@ -134,7 +134,7 @@ All incoming data is validated and sanitised, and anything unexpected is simply
|
|||||||
|
|
||||||
## Configuration
|
## 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
|
## Troubleshooting
|
||||||
|
|
||||||
|
|||||||
@@ -96,7 +96,7 @@ export async function downloadAssets (res: Response, share: SharedLink, assets:
|
|||||||
|
|
||||||
const options: StagingOptions = {
|
const options: StagingOptions = {
|
||||||
stagingDir: await fs.mkdtemp(join(tmpdir(), STAGING_DIR_PREFIX)),
|
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,
|
maxAttempts: 3,
|
||||||
headerTimeoutMs: 20_000,
|
headerTimeoutMs: 20_000,
|
||||||
idleTimeoutMs: 20_000
|
idleTimeoutMs: 20_000
|
||||||
|
|||||||
+15
-10
@@ -18,24 +18,30 @@ export default defineConfig({
|
|||||||
provider: 'local'
|
provider: 'local'
|
||||||
},
|
},
|
||||||
nav: [
|
nav: [
|
||||||
{ text: 'Guide', link: '/getting-started' },
|
{ text: 'About', link: '/introduction' },
|
||||||
{ text: 'Configuration', link: '/configuration' },
|
{ text: 'Configuration', link: '/config/' },
|
||||||
{ text: 'Live demo', link: DEMO_URL }
|
{ text: 'Live demo', link: DEMO_URL }
|
||||||
],
|
],
|
||||||
sidebar: [
|
sidebar: [
|
||||||
{
|
{
|
||||||
text: 'Getting started',
|
text: 'Getting started',
|
||||||
items: [
|
items: [
|
||||||
{ text: 'Introduction', link: '/' },
|
{ text: 'Introduction', link: '/introduction' },
|
||||||
{ text: 'Installation & usage', link: '/getting-started' }
|
{ text: 'Installation', link: '/installation' },
|
||||||
|
{ text: 'How to use it', link: '/how-to-use' },
|
||||||
|
{ text: 'Troubleshooting', link: '/troubleshooting' }
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
text: 'Configuration',
|
text: 'Config options',
|
||||||
items: [
|
items: [
|
||||||
{ text: 'Configuration reference', link: '/configuration' },
|
{ text: 'Overview', link: '/config/' },
|
||||||
{ text: 'Inline (docker-compose) config', link: '/inline-configuration' },
|
{ text: 'IPP options', link: '/config/ipp-options' },
|
||||||
{ text: 'Customising web responses', link: '/custom-responses' }
|
{ 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'
|
text: 'Edit this page on GitHub'
|
||||||
},
|
},
|
||||||
footer: {
|
footer: {
|
||||||
message: 'Released under the AGPL-3.0 licence.',
|
message: 'Released under the AGPL-3.0 licence.'
|
||||||
copyright: 'Copyright © Alan Grainger'
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
})
|
})
|
||||||
|
|||||||
@@ -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;
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -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:
|
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. |
|
| 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. |
|
| 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:
|
Possible options are:
|
||||||
|
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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).
|
||||||
@@ -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}`).
|
||||||
@@ -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 }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
@@ -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.
|
||||||
@@ -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.
|
|
||||||
@@ -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).
|
|
||||||
@@ -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
@@ -5,22 +5,16 @@ hero:
|
|||||||
name: Immich Public Proxy
|
name: Immich Public Proxy
|
||||||
text: Share your photos safely
|
text: Share your photos safely
|
||||||
tagline: Share your Immich photos and albums publicly without exposing your Immich instance to the internet.
|
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:
|
actions:
|
||||||
- theme: brand
|
- theme: brand
|
||||||
text: Get started
|
|
||||||
link: /getting-started
|
|
||||||
- theme: alt
|
|
||||||
text: Configuration
|
|
||||||
link: /configuration
|
|
||||||
- theme: alt
|
|
||||||
text: Live demo
|
text: Live demo
|
||||||
link: https://immich-demo.note.sx/share/gJfs8l4LcJJrBUpjhMnDoKXFt1Tm5vKXPbXl8BgwPtLtEBCOOObqbQdV5i0oun5hZjQ
|
link: https://immich-demo.note.sx/share/gJfs8l4LcJJrBUpjhMnDoKXFt1Tm5vKXPbXl8BgwPtLtEBCOOObqbQdV5i0oun5hZjQ
|
||||||
- theme: alt
|
- theme: alt
|
||||||
text: View on GitHub
|
text: Getting started
|
||||||
link: https://github.com/alangrainger/immich-public-proxy
|
link: /introduction
|
||||||
|
- theme: alt
|
||||||
|
text: Configuration
|
||||||
|
link: /config/
|
||||||
|
|
||||||
features:
|
features:
|
||||||
- title: Locked down by design
|
- title: Locked down by design
|
||||||
@@ -32,3 +26,4 @@ features:
|
|||||||
- title: Managed entirely in Immich
|
- 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.
|
details: All sharing stays managed within Immich itself. Set IPP up once and you never need to touch it again.
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -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,
|
|
||||||
...
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
@@ -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).
|
||||||
@@ -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).
|
||||||
@@ -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.
|
||||||
Reference in New Issue
Block a user