Docs WIP
This commit is contained in:
+15
-10
@@ -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.'
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
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.
|
||||
---
|
||||
|
||||
|
||||
@@ -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