From ff45919107ebb986b32fb53e6f73367ff7779b55 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Fri, 4 Sep 2026 12:55:08 +1200 Subject: [PATCH] Update docs --- CONTRIBUTING.md | 16 +- README.md | 141 +++--------------- docs/.vitepress/config.ts | 35 +++-- docs/.vitepress/theme/index.ts | 3 +- docs/README.md | 78 ++++++++++ docs/config/environment-variables.md | 51 +++++++ docs/config/gallery.md | 2 +- docs/config/index.md | 17 +-- docs/config/ipp-options.md | 23 ++- docs/config/metadata.md | 26 ---- docs/config/upgrading.md | 4 +- docs/external-link.png | Bin 974 -> 0 bytes docs/how-to-use.md | 45 +++++- docs/index.md | 4 +- docs/installation.md | 17 ++- docs/introduction.md | 28 +++- docs/kubernetes.md | 25 ++-- docs/{ => public}/cloudflare-video-cache.webp | Bin docs/{ => public}/screenshot.webp | Bin docs/{ => public}/server-settings.png | Bin docs/{ => public}/share-link.webp | Bin docs/securing-immich-with-mtls.md | 14 +- docs/shield.png | Bin 16618 -> 0 bytes docs/upgrading.md | 29 ++++ 24 files changed, 349 insertions(+), 209 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/config/environment-variables.md delete mode 100644 docs/external-link.png rename docs/{ => public}/cloudflare-video-cache.webp (100%) rename docs/{ => public}/screenshot.webp (100%) rename docs/{ => public}/server-settings.png (100%) rename docs/{ => public}/share-link.webp (100%) delete mode 100644 docs/shield.png create mode 100644 docs/upgrading.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f9877a..110bfe9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,7 +65,7 @@ app/ thumbhash/, fonts/, images/ style.css, photoswipe-overrides.css tests/ Vitest unit tests for pure functions -docs/ User-facing docs linked from the README +docs/ User docs site (VitePress); docs/README.md explains its structure Dockerfile Multi-stage build, runs as the non-root `node` user docker-compose.yml Reference deployment ``` @@ -102,8 +102,9 @@ Required environment variables (set in `app/.env` or your shell): - `IMMICH_URL` - local URL to your Immich instance. Should not be public. - `PUBLIC_BASE_URL` - optional. Public base URL for IPP without trailing slash. Omit to derive from request hostname. - `IPP_PORT` - optional. Default 3000. +- `IPP_CONFIG` - optional. Path to a config file. All variables: `docs/config/environment-variables.md`. -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 docs site has the user-facing setup steps (`docs/installation.md`). 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. @@ -125,7 +126,7 @@ Beyond unit tests, exercise the gallery end-to-end against a real Immich instanc ## Conventions for adding code -**Configuration.** New options go in `app/config.json` under the appropriate `ipp.*` namespace, read via `getConfigOption`, and documented in the relevant table in `README.md`. Prefer a group toggle plus per-field overrides over a single flat boolean when several related toggles cluster, following the `ipp.showMetadata` pattern. Existing keys keep working; if you rename one, add a backward-compat shim with a startup deprecation warning, as was done for the v2.0 gallery key rename. +**Configuration.** New options go in `app/config.json` under the appropriate `ipp.*` namespace, read via `getConfigOption`, and documented on the page for their group under `docs/config/` (see `docs/README.md` for the conventions). Prefer a group toggle plus per-field overrides over a single flat boolean when several related toggles cluster, following the `ipp.showMetadata` pattern. Existing keys keep working; if you rename one, add a backward-compat shim with a startup deprecation warning, as was done for the v2.0 gallery key rename. **Privacy of responses.** Always return 404 for invalid or upstream-failed requests. Use `invalidRequestHandler` rather than crafting ad-hoc error responses. Do not surface Immich status codes or error bodies to the client. @@ -145,6 +146,12 @@ Where to put a new function: ask what category of thing it is, not where it gets **Code style.** ESLint standard config. Run lint locally before opening a PR. +## Documentation + +User-facing documentation is the VitePress site in `docs/`, published at https://docs.ipp.nz. Read `docs/README.md` before adding or moving a page: it sets out the four sidebar groups (Getting started, Configuration, Guides, Troubleshooting - one per kind of content in the Diátaxis sense), where each kind of new material belongs, and the page conventions. Run `npm run build` inside `docs/` before pushing; the build fails on dead internal links. + +The root `README.md` is a front door only: pitch, demo, quick start and links. New content goes on the site. + ## Release process Releases are triggered by pushing a `v*` tag. The `.github/workflows/ci.yaml` workflow builds a multi-arch (`linux/amd64`, `linux/arm64`) image, pushes to both GHCR and Docker Hub, and attaches a build-provenance attestation to each registry. @@ -161,7 +168,7 @@ Do not push tags as part of a PR; releases are cut by the maintainer. For anything non-trivial, open a [Feature Request discussion](https://github.com/alangrainger/immich-public-proxy/discussions/categories/feature-requests) first. The maintainer would rather discuss fit with the read-only/lean philosophy before you spend time on a PR. - Branch from `main`. -- Update the README config tables if you added or changed config keys. +- Update the page under `docs/config/` if you added or changed config keys, following `docs/README.md`. - If your change has a user-visible behavior, include a one-line note in the PR description about how to exercise it. ## What will not be accepted @@ -188,5 +195,6 @@ If you are an AI coding agent working on this repo, the rules above apply to you - **Do not add error handling for cases that cannot happen.** Trust internal invariants. Validate only at the boundary (incoming request, Immich response). - **Default to writing no comments.** Add a comment only when the *why* is non-obvious: a security-relevant invariant, a workaround for a specific upstream bug, or behavior that would surprise a careful reader. Do not narrate the *what*. - **Match the project's existing style.** Server-side Preact SSR, TypeScript ES modules on the client (compiled by `tsc`, no bundler, no framework), plain CSS. Do not introduce new patterns without discussion. +- **Docs changes follow `docs/README.md`.** New material goes in the sidebar group that matches its kind (tutorial, reference, guide, troubleshooting); published page paths stay stable; defaults are checked against `app/config.json`. If something in this guide conflicts with an instruction you have been given, stop and raise the conflict rather than silently working around it. diff --git a/README.md b/README.md index 08ed709..997823d 100644 --- a/README.md +++ b/README.md @@ -20,143 +20,48 @@ serving straight out of my own Immich instance. Setup takes less than a minute, and you never need to touch it again as all of your sharing stays managed within Immich.
-
+
-
-Now whenever you share an image or gallery through Immich, it will automatically create the correct public path for you.
-
-🚨 **IMPORTANT**: 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/...` and `/s/...`, you can run Immich Public Proxy and Immich on the same domain.
-
-See the instructions here: [Running on a single domain](./docs/running-on-single-domain.md).
-
-#### Redirecting your root domain to a share
-
-Want `photos.yourdomain.net` to open a specific album instead of the IPP landing page? You can do this with your
-reverse proxy - see [Redirecting your root domain to a share](./docs/redirect-root-to-share.md).
-
-### Install with Kubernetes
-
-[See the docs here](docs/kubernetes.md).
-
-## 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 automaticaly have the correct URL:
-
-
-
-## How it works
-
-When the proxy receives a request, it will come as a link like this:
-
-```
-https://your-proxy-url.com/share/ffSw63qnIYMtpmg0RNvOui0Dpio7BbxsObjvH8YZaobIjIAzl5n7zTX5d6EDHdOYEvo
-```
-
-The part after `/share/` is Immich's shared link public ID (called the `key` [in the docs](https://immich.app/docs/api/get-my-shared-link)).
-For shared links with a named slug, the link will use the slug instead, e.g. `https://your-proxy-url.com/s/my-album`.
-
-**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 docs](https://docs.ipp.nz/config/)** for the full reference.
-
-## Troubleshooting
-
-See the [troubleshooting docs](https://docs.ipp.nz/troubleshooting).
+- [Installation](https://docs.ipp.nz/installation) and [Sharing from Immich](https://docs.ipp.nz/how-to-use)
+- [Configuration](https://docs.ipp.nz/config/): downloads, gallery layout, lightbox, metadata privacy, error responses
+- Guides: [single domain with Immich](https://docs.ipp.nz/running-on-single-domain),
+ [redirect your root domain to a share](https://docs.ipp.nz/redirect-root-to-share),
+ [securing Immich with mTLS](https://docs.ipp.nz/securing-immich-with-mtls)
+- [Troubleshooting](https://docs.ipp.nz/troubleshooting)
## 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 accesss, it won't be considered as a new feature.
-- Uploading photos (see above).
-
-The second rule is that "IPP is stateless and does not know anything about your Immich instance". Anything that would require storing a share key (i.e. the code which gives you access to a share) is unlikely to be added.
+IPP has **read-only** access to Immich and stores nothing: anything that needs an API key, modifies Immich, or would
+require storing a share key won't be considered. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full list.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index b7b75be..c9d252e 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -1,6 +1,5 @@
import { defineConfig } from 'vitepress'
-const DEMO_URL = 'https://demo.ipp.nz/s/demo-gallery'
const REPO_URL = 'https://github.com/alangrainger/immich-public-proxy'
export default defineConfig({
@@ -9,6 +8,8 @@ export default defineConfig({
lang: 'en-NZ',
cleanUrls: true,
lastUpdated: true,
+ // README.md is the maintainer's guide to this site, not a page.
+ srcExclude: ['README.md'],
head: [
['link', { rel: 'icon', href: '/ipp.svg' }]
],
@@ -20,39 +21,49 @@ export default defineConfig({
nav: [
{ text: 'About', link: '/introduction' },
{ text: 'Configuration', link: '/config/' },
- { text: 'Github', link: REPO_URL, target: '_self' }
+ { text: 'Releases', link: `${REPO_URL}/releases`, target: '_self' }
],
+ /* One group per kind of content (tutorial, reference, how-to, troubleshooting).
+ README.md in this folder explains the split; read it before adding a page.
+ Paths are public URLs: change a label or heading, never a path. */
sidebar: [
{
text: 'Getting started',
items: [
{ text: 'Introduction', link: '/introduction' },
- { text: 'Installation', link: '/installation' },
- { text: 'How to use it', link: '/how-to-use' },
- { text: 'Troubleshooting', link: '/troubleshooting' }
+ {
+ text: 'Installation',
+ link: '/installation',
+ items: [
+ { text: 'Kubernetes', link: '/kubernetes' }
+ ]
+ },
+ { text: 'Sharing from Immich', link: '/how-to-use' },
+ { text: 'Upgrading', link: '/upgrading' }
]
},
{
- text: 'Config options',
+ text: 'Configuration',
items: [
{ text: 'Overview', link: '/config/' },
- { text: 'IPP options', link: '/config/ipp-options' },
+ { text: 'Environment variables', link: '/config/environment-variables' },
+ { text: 'General 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' }
+ { text: 'Legacy config keys', link: '/config/upgrading' }
]
},
{
- text: 'Deployment',
+ text: 'Guides',
items: [
{ text: 'Single domain with Immich', link: '/running-on-single-domain' },
{ text: 'Redirect root domain to a share', link: '/redirect-root-to-share' },
- { text: 'Securing Immich with mTLS', link: '/securing-immich-with-mtls' },
- { text: 'Install with Kubernetes', link: '/kubernetes' }
+ { text: 'Securing Immich with mTLS', link: '/securing-immich-with-mtls' }
]
- }
+ },
+ { text: 'Troubleshooting', link: '/troubleshooting' }
],
socialLinks: [
{ icon: 'github', link: REPO_URL }
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 530a1d2..5116fbb 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -1,6 +1,5 @@
import DefaultTheme from 'vitepress/theme'
import { h } from 'vue'
-import screenshot from '../../screenshot.webp'
import './custom.css'
const DEMO_URL = 'https://demo.ipp.nz/s/demo-gallery'
@@ -44,7 +43,7 @@ export default {
},
[
h('img', {
- src: screenshot,
+ src: '/screenshot.webp',
alt: 'Immich Public Proxy gallery screenshot',
style: 'width: 100%; border-radius: 12px; box-shadow: 0 6px 24px rgba(0, 0, 0, 0.12);'
})
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..4e5716d
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,78 @@
+# Docs site
+
+The user documentation at [docs.ipp.nz](https://docs.ipp.nz), built with [VitePress](https://vitepress.dev). This
+file is the maintainer's guide to the site and is excluded from the build (`srcExclude` in `.vitepress/config.ts`).
+Read it before adding or moving a page.
+
+## Contents
+
+- [Working on the site](#working-on-the-site)
+- [Structure](#structure)
+- [Where new content goes](#where-new-content-goes)
+- [Page conventions](#page-conventions)
+- [The README](#the-readme)
+
+## Working on the site
+
+```bash
+cd docs
+npm install
+npm run dev # live preview
+npm run build # fails on dead internal links; run it before pushing
+```
+
+The sidebar is hand-maintained in `.vitepress/config.ts`, so a new page is invisible until it is added there.
+Publishing the built site is a manual step done by the maintainer; a push to `main` does not deploy anything
+by itself.
+Static files (images, favicon) live in `public/` and are referenced by absolute path, e.g. `/share-link.webp`.
+
+## Structure
+
+The site follows the [Diátaxis](https://diataxis.fr) model: every page is one of tutorial, how-to guide, reference or
+explanation, and a page never mixes kinds. Each sidebar group holds one kind and is named for the reader's question
+rather than the Diátaxis term.
+
+| Group | Kind | Reader's question | Rules |
+|-----------------|-----------|--------------------------------------------|-------|
+| Getting started | Tutorial | What is this, and how do I get it running? | Ordered as a path: Introduction, Installation, Sharing from Immich, Upgrading. Numbered steps, one happy path, defaults only. Link to reference pages rather than explaining options inline. |
+| Configuration | Reference | What does this key do? | One page per `ipp.*` group, mirroring `app/config.json`. Every key has a `**Type:** … · **Default:** …` line and a short description; each page opens with a worked example. Complete and neutral: no advice, no tutorials. |
+| Guides | How-to | How do I achieve this goal? | One goal per page and the title names the goal. Assume IPP is installed. Label every config block with the proxy or platform it is for; Caddy first, then others. |
+| Troubleshooting | How-to | Why is this happening? | One page, one `##` per problem. The heading is the symptom as the user sees it (a log line, or what they observe), then the cause, then the fix, then links to the GitHub issues. |
+
+Explanation (how IPP works, the security model, design principles) lives in **Introduction**. It sits in Getting
+started because it is what people read first, not because it is a tutorial. If explanation outgrows one page, add a
+"Concepts" group rather than pushing "why" material into a guide or a reference page.
+
+## Where new content goes
+
+| You are adding… | Put it in |
+|------------------------------------------------|-----------|
+| A config key | The page for its group, in `config.json` order, with type and default. If you renamed a key, add a row to Legacy config keys and a shim in `app/src/config/migrations.ts`. |
+| An environment variable | `config/environment-variables.md` |
+| Something visitors to a share will notice | `how-to-use.md` (Sharing from Immich) |
+| A reverse-proxy or hosting recipe | A new page under Guides |
+| The fix for a recurring support question | `troubleshooting.md`, symptom first |
+| A design decision or a "why" | `introduction.md` |
+| Developer or contributor information | `CONTRIBUTING.md` at the repo root, not the site |
+
+## Page conventions
+
+- The H1 is the sidebar label. The first paragraph says what the page covers.
+- Paths are public URLs, linked from GitHub issues and forums: do not rename or move a published page. Change the
+ sidebar label and H1 instead. That is why "General options" is served from `/config/ipp-options` and "Sharing from
+ Immich" from `/how-to-use`.
+- Internal links are absolute site paths with optional anchors (`/config/gallery#showtitle`), never relative file
+ links. Anchors are the heading text lowercased with backticks stripped and spaces as hyphens; keep headings that
+ are link targets free of other punctuation.
+- Config keys are written as `` `gallery.showTitle` `` and linked to their section the first time they appear on a page.
+- Callouts use GitHub syntax (`> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`) and are kept for things that bite.
+- Code fences are tagged `yaml`, `json` or `bash`. Caddyfiles use a plain fence; there is no highlighter for them.
+- Images are `
` with real dimensions so the page does not shift
+ while loading.
+- Types and defaults come from `app/config.json` and the code. Check, don't guess.
+- British English, hyphens rather than dashes, and "IPP" after the first "Immich Public Proxy" on a page.
+
+## The README
+
+`README.md` at the repo root is the front door, not a second copy of the site: pitch, demo, screenshot, quick start
+and links. When something is worth documenting, it goes on the site and the README links to it.
diff --git a/docs/config/environment-variables.md b/docs/config/environment-variables.md
new file mode 100644
index 0000000..3633864
--- /dev/null
+++ b/docs/config/environment-variables.md
@@ -0,0 +1,51 @@
+# Environment variables
+
+Connection and runtime settings are passed as environment variables, typically in the `environment` section of your
+`docker-compose.yml`. Only `IMMICH_URL` is required. Everything that controls how shares look and behave is JSON
+config instead; see the [Configuration overview](/config/).
+
+## `IMMICH_URL`
+
+**Required**
+
+The URL of your Immich server as reached from inside the IPP container, for example `http://immich_server:2283`.
+Use the local address, not your public one: IPP is the only thing that needs to be public. A trailing slash is
+ignored.
+
+From inside a container, `localhost` does not reach Immich. If IPP logs "Unable to reach Immich" at startup, see
+[Troubleshooting](/troubleshooting).
+
+## `PUBLIC_BASE_URL`
+
+**Optional** · **Default:** derived from each request
+
+The public base URL of IPP without a trailing slash, for example `https://your-proxy-url.com`. The gallery uses
+relative URLs everywhere except the `og:image` tag that messaging apps read for link previews, which must be fully
+qualified. When unset, IPP builds it from the incoming request's protocol and `Host` header.
+
+Set it if link previews show `http://` or a private address. Leave it unset if you serve IPP from several domains,
+and make sure your reverse proxy forwards the original `Host` header.
+
+## `IPP_PORT`
+
+**Optional** · **Default:** `3000`
+
+The port the web server listens on inside the container. If you change it, update the `ports` mapping and the
+`healthcheck` in your compose file to match.
+
+## `IPP_CONFIG`
+
+**Optional** · **Default:** `/app/config.json`
+
+Path to the JSON config file, either absolute or relative to the working directory. Use it to keep the config
+somewhere other than the default path. The usual approach is to mount your file over the default path instead, as
+described in the [Configuration overview](/config/#mount-a-file).
+
+## `CONFIG`
+
+**Optional**
+
+The JSON config as an inline string. When set, no config file is read at all. See
+[Inline via env var](/config/#inline-via-env-var) for an example.
+
+`APP_VERSION` and `NODE_ENV` are set by the Docker image and are not meant to be changed.
diff --git a/docs/config/gallery.md b/docs/config/gallery.md
index d01adcc..d761262 100644
--- a/docs/config/gallery.md
+++ b/docs/config/gallery.md
@@ -85,6 +85,6 @@ Show the bulk-zip download UI - the "download all" button in the header and the
## `cacheTime`
-**Type:** `int`
+**Type:** `int` · **Default:** `300`
How long (in seconds) browsers and any CDN may cache the gallery **page** before revalidating. Set this longer to reduce load on your server, but be aware that if you add new photos to a gallery they won't show up until the cache times out or you manually clear any downstream caches.
diff --git a/docs/config/index.md b/docs/config/index.md
index ee860db..120a448 100644
--- a/docs/config/index.md
+++ b/docs/config/index.md
@@ -3,21 +3,22 @@
> [!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:
+Connection settings (the Immich URL, public URL, port and config file location) are
+[environment variables](/config/environment-variables). Everything else is JSON config under `ipp.*`, grouped into:
-- [IPP options](/config/ipp-options) - top-level proxy behaviour.
+- [General options](/config/ipp-options) - downloads, zoom quality, slug links, response headers.
- [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.
+- [Legacy config keys](/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.
+> You only need to include the keys you're changing. Anything you omit keeps its default, and the defaults are always the most privacy-respecting option. In particular the metadata groups are per-field opt-in: nothing is exposed until you set its flag to `true`, including fields IPP adds in future versions.
-There are two ways to supply custom config.
+There are two ways to supply custom config. If both are present, `CONFIG` wins and the file is not read.
### Mount a file
@@ -45,9 +46,3 @@ For one-off or single-key overrides, pass the configuration inline from your `do
}
}
```
-
-## How options are organised
-
-All options live under `ipp.*`. The metadata groups (`ipp.showMetadata.exif`, `ipp.showMetadata.location`) are per-field opt-in: every field is off until you explicitly set its flag to `true`. Nothing is automatically exposed - including fields IPP adds in future versions.
-
-You only need to include the keys you're changing. Anything you omit keeps its default.
diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md
index 980d6e0..af984b3 100644
--- a/docs/config/ipp-options.md
+++ b/docs/config/ipp-options.md
@@ -1,6 +1,6 @@
-# IPP options
+# General options
-Top-level options under `ipp.*`.
+Top-level options under `ipp.*` that don't belong to the [Gallery](/config/gallery), [Lightbox](/config/lightbox) or [Metadata](/config/metadata) groups.
## Example
@@ -19,7 +19,18 @@ Serve full-resolution images both when zooming in the lightbox and when download
**Type:** `object`
-Change the headers sent with your web responses. By default there is `cache-control` and CORS added.
+Change the headers sent with your web responses. The default is a 30-day `Cache-Control` and a permissive CORS header:
+
+```json
+{
+ "ipp": {
+ "responseHeaders": {
+ "Cache-Control": "public, max-age=2592000",
+ "Access-Control-Allow-Origin": "*"
+ }
+ }
+}
+```
## `maxDownloadQuality`
@@ -77,13 +88,13 @@ The bulk-zip and per-asset buttons can be toggled independently once downloads a
## `allowSlugLinks`
-**Type:** `bool`
+**Type:** `bool` · **Default:** `true`
-Enable/disable the custom URL links.
+Serve shared links that have a custom URL in Immich at `/s/
+
+## Share links
+
+A standard link looks like `https://your-proxy-url.com/share/N93(TImTUQ52>w>Lz`+ z%^UPUhhyZ7O^5Z3>;Zi+9`>Q8OdM(5GCY-FC!Yh&ax$i$!!rXY3IBUr2lr=07x{(?hf>_K-1EFgaIqhSGuR{%T z{hW%5!`6P~iCr%Hb;nxJ!=D4U2iVI>+FHgn+;2Q6&jL9|@6j;f3+xFw{!2)?N=-@f zB1vF;VZuisE) yS!>;|IQT{4;@CAvuiN-ER&MC4NO@WG=L~U$lG&8Ty$r+=hPL1T=z?~bW_201O zd C2#D-6%Wc$B?w z?WeK|(bH>PyH7n~;kDS21&A)dJr6@y5Ia|nf7N_a-=O$4Ms6@BFH047?ZC@)17c*K zA^M^iTByeV_hVe`m<8OFf0nJc8bgHVOJVdTDW-QT&hnr X5R|p7Z&RWSY?^3U4WPm=wwWr&lQ85@8A6-x62&N683f5pYmO7$(SbNWngZs zQ0;%NYxAV?S>j;kee{+8k+fa2zncWzYTC3GkfPi3j20o3h@DuI4?B5l%6> b$-oW&ri^p(6ouQUF7AB-YAnhI#ZQQA*oeG&Z$2g<} zOwtUTq9~9KMmZTR+nN2HIgBm+%6z+dd7Ee4$aL<&@1VfhuRz%($y>E^*8-^_eELPi z=oFjTl+(vf4$|OSbTWpwsKisn3J%`Pgr7>AE=3bKoLnr9p86WDFZqCAvc^QXAkLkq zX{dcrukZ>ZFS`z|y)i0ey=byb)Hq#X5+8M-j-bC9K;G<}MO}AG^sa)+_R%7lW`Kk+p~f+ Ty8C9r)Jj+xlPGlnGhn%2G%{CI^W0D5YMfs1nq)OXd$aeYHsB(vv~{O z_H`+=4Vx{kw*s+5Kg%3xuG}v(2#ad z)Mf|E>c0|KKcUxoCUCR_ zk Lp2Y>x};jlx( zoBj;5jGym7tB9=Y$FX{^Eh=)_w}NAI`cG>>*BNQJ4q_Icw<_T>GHJ;~O?>%<|Bfq9 z>`XnoK>T%h9kLp}>FDJ;H O)5_lpg(B zy;lx35aOunxy!>$I06wT&y|eL&E7X#hOgtxy-?=F{;tR=AcYp_+1`D24-Rb5JX3Fc zOlmX zky1O~ytz{3ejYFFQHl3r*35e622+X&^9fFPEOS1oIP1^z%~JO_jo*R)^hP#f!vhFM zlQISEq>jugUX=O!?#*}@fGG)WFG$j?2_C&|tdgRzF@Xl y>3i|k?@ z8U+)dvI~o7b17I#(VRBQn+6eg3oDBB+gVT|yrFOX31*XhKO&SQQ5{mcq_}0rknWZZ8 zWK+%8jAs9~CsHjZBNjsd)0-wrW-6xczvond3O5sr^67L*Od&56&zLA*r2hvp!}o=e z4S!p94#+zVF3eP%ivRw{m^`ZZ{TytP{f5>@`qv^BJ@ExA@ Kt%12sD{aGHbx%D+@h9D7&r7bcS f?eozEYSlmFLEPF8PYJ9`;c^HbWFKeztA? z>n4$xw3VB*Cn~C{{Pv179!}35N;Nt+J`f_hD3%|`CjLfxVsCvxYk0-q&Hoc$cO#Bb zvUe`$6}iyQtL2(W9d8nGs=_Iu0ydGQ+K)rZHs58br3Lp?569L1nN$AAl5+}`1V2|q zWO>Dz+%+|iRiRj6*l-KY 0biMj=0>u>t;sX?5d`^G^8W ztM2+wYNOx=6BM&BCC*Nm&HOoVl2vlg0di7yj|mAfb`erL86?P)OvT%lzdgjf!A3o( zPk6pS8gR a9J;A7E_=A@+ib6l0>k zw4_b{%EVZd3p7E~=ut7We+?ha-G3o&v4!JdcKPp2-_l2Wv$?i@znhQwk1Qg=`q@zK zWfK9G*Z$Nu>Aoqs1L9Wl{_n9xWZ^|6IJ2uf(W?}^F4{z&n-pl~#4`)WyC??@%GiNG zsk5Sz_7!&Fzlprb$d7c3otM8>kvX6a?&l%?h1W$T2|vWX4>dN01uImIvU^q%$l*$m zb@MzC$ m(IF0+X5NIP} zoHmlo%VykLgmO^YwDD@`H#&Q}NLs%zEzQETJLdF~Q#515jhEH1R}uZqO{-d|s^v>M zAxE)h#NL8IwLmI@VSd#N?^V=^2P$A1FBap?6ylA=(cm>Jm(LQRsE}9lU%?~Gl29B$ zM*+5dRhw^1n=>wI>bJqS#UT&V0#fQ_+gU2>q=E{%A+#uv`tm1K^d8SdM&` ig&;gG0cLgibNF$Y(&l z8&}*^Huo#e{1$@k{|r?;VIPI7(=O)WgXLSRxcd!a_%}$8{Pb2j;ZyB+bZBXFh`G&q zKC`U#!=)9~ZEC8TE-Q8T<3N>?G**%xjFtfH>HDXy5j<=D=XdvGSHX) (LckiQ1!LCJ<@9v-@hn@&50{bKgE4Q)c3d+09mX)_-*mD$V-F0@b2To9 zSCfY{VcUFgk|27+X798dq~&*RpB0br0l6YfV=tcZhcj94-?c&qG8ynvg%Z&Hrmw6Z zuTEa$4}?kX#98a&&*Qyk-KPuFhi;%dYjq&ZRF$6)OoE$*M^9$V`%0QudStxowB!Cd zx8<3dy8R;ZA!Aul`(gmG7Cs!+8(zVgUQ&`DQ&yMySe{czjT;7Ho!u4WyN)Sb0WKs= zseGPzFKRJ=m-`tiv-&`63iv66f{wz|=YYNxBjrN$CwxwIjN>aO*$Zi>l7pO~ulB>E zo^;GI0%`0J5*03%ZwENbWOqKg@2f }av`{PI1?;+Q3HEZ_fYzzJp6NqT% zHLWV5C4IS9n)^~8tF@lLc{nXjy*>j|O)OI0;3D5)$okU@TIC7*;(6QZAvQLq@Q-=D z9)rD7u3w2zO^`ht7HbCDNA8s-Ner`aznA&?;zyV?{z15i-NQTe6SKa@`>>6JWxMj4 zUU3 ZC0vxW&eXLz`hD80C;~*B4Tox#yyV*H zvQhBBOUq)G@pfs&oV58;Q-W{BoKOZ6>T1O;bLh(3KWGo$E_|@U(n%X#@ar0RybT-o zSpF?v>v9#LstQh^ke)O@%Bhb5CrV~l7hd=!P?=JE)MA?byRof;;@n DVvl=;0(W5l)^NGmP*F<6A;^b>3JFBQVUdwLgaK$v@%KI|np z>Nx2TYXB9c8MA#01nRC0; +nbr8`8 z$XjwrOS9}dmsA_yWChEeUQ||C#W4l=nm1@?zoSsTQF_3hbH_HCLnr_;edhhUuZS@B z{x`{(6IPw$ fqERQ{J61H$CFqJvYVK$qsr} @vURBY{H611dibS{ zNk_aa`kfGtlV{hvAlT>bUY$o_(HMsN=Rac3lhuy?O3c|!VYgeajU#M+^`ucpB!cfB zOtNdzZ5+50VNOx6ftqKO1sFCFz3+}uGZ;)~kqNTJ&iB_QCbj9d4o^s#Zm_Eng*NOL z-YldCQtKtzz(vQao5z?h7b54T+0;xc*Q*IcLjLkGj94 2DroUI0wPh&Rfhz@=8jvksy!k5u? o#Bsg{*$` q_l zE3R%?|E_ywQ$P1tF@w*r%|g(3Ra2A@@cp5IyDj6<$%@rj8F{GduiIa>%J~_C>Jevj zcGAGO0xNVLoJ3zW-%Cl-BKV6E !&vUnyl54I%p{AECqh$wh_8`!WTH4lu6 zldmzEa0B&*jr_KzRZA1320kPoyAPWcsWDp88!+fnnYmj&{4jOTzE3R2nv5m}J)aF< z2&X~;(G-T%oe@-lr`aW%j|TBu8c{X7k=$tdIw2p}Zdjrn35yrzHZ>0@F(~ViPd4m8 z_^CQ=VhNV}_iMjc!gxVE_kCRN5Q01`^kB^z%4ehSPw~Lxuq^M$<7bn6u}39?D8uG} zkE=m0r_Gig5v-Bbs&wM`l$G-XAIr5Okk<8EAnWJvyH9agjvo9@aeng5jdtwFVlDYE zgyPZ5+UjGbB%8Ruz)Sl)$BB1$;ClUd8&5kWJFXqhrIH%b@#1f#*Ihsaolal<>roVK z6DyJ@70i<)Qg$ 5lg5Ac{ryCZ)I5&q4sh4AzO5#W>v( z1sH@O#W&sEUrsk%pT5r$gjD8l`#3c@m$v*@JRjgFQXDZU^V#?)G9kGi AmJb*FhU`wZJ)`8DSs=dp47NyP@Kpo+i!DWOjM@BX KWX_V=3}+`M1uyg?6v+Hzbypvh*%qvh7usP5MqUHPpP?pE6_V zQ1p&y$jFI~l~z2p 4CvhRRX#F1_%q;}7f J 44qbb{@G*uWOpG}ylpDc%{C660VIXH3W zYKW+yLZuNWjIm}2`6MoMt8r7*n7jLbnZ>Ovsyf-zWTz=k7cQZbLVW8V`v<`Ddlx3g z&w78~m1*l(8nju&qC<7P1RwgpgZ}b2qDE!D9o`yLw@UIktJ8elBFpHHA@M`L3E=Y2 z6olt~uE@C(h`aD2H44`<<0Q=%4es>Bwu)-`4JeQ<#lOZ I*54ce>w#H8?J`{3|mb)POIZxh292f^EMeh^#NirT2C_(M)9)B??VB6k^1(B?4 znN`&Cee}GTd3{eIKXVw#YvLdMtbi&|2$Rw&3?8UO-TpHE^+QXm`W68l5x>AxnVQEd zKNZV>%#P0G03rL15FN#NC;1=4FWW2@7Rbo94yru8VyoNF{ye_>kM~aw*v V;trcqW8>^F*pS!rs6BLa_B?wz^Ye8_M}gU|E(M=0%~s)i`)eDSyRe(bgA<=E z^A7WZkm4otxydybchCBIe!h=iA4Ww*AbulAQ#pRX0cB$&EPL;?lg()InO#DQ6&ixq zYCs&7TS{QV&$3x; #MN~InN`^moJoz`KNnQxo{u{e( xc6m)|U7)8BE3sc--gTt(h_e)|1 z!6FVGSW_|+At R%$MC5u@r z*`v0R1?-UcgxsX3r%59X`W`k^e`&rT1cpF4)u7{q+-0DGkD{E#aPUTv)Kud=5;qJM zlUN25r6GA&CjxoeVf0Wj?TIw+6+>mZu*1H}5ohH-8{_ReaUX)Z(3>*Za>d0U-7xkb z_bO7z)eKeAl0}p fzP{D*^!K=ss7H;K~3~`z p7NM7o_!R~YjwGItQfhiq?DX9ij5eT1ki2P%(q0BK}Qu*?4L|@ zB}6_$DFq&I(Hr!DLGJxI`sZjIzZMa~0J%vEFuTfe^=Vexwk>DNRd3;g6P7pk_=$(e z>nQ%YgZLPw #(XOE1w&hs88T*^{|OfWU56A `&)biS79U6Tct=8NTBLEDZKB+dPk|tig(?K@Py@C;WbDqW zC*8KdHO*rx PraLUsX^-1amhP49s7h%z;&;ZqYyM@`f!bO_& zwuYYX{@3##tRe?=&(1mJGxx5gU_Wyd{g-Y5wV4mEuNuKx#Sm1C!!KnLw!soSZ5>O5 ziV4=jqFjHCx=ZIOR57Dp#iOS9)cy@VAFD#gNtiFSL|r#De3evFRi~yz63kO%cX1Q* z(J`t@U(2wD0o5yud}H?!hE=3TfCfI-^0`~$4wGKsINL`BbrT@=Tm;?VFtCWTfnchW zj&rr*7e-0kUIKm$m_|875H12k;f~HWd#iOxl>yw)7aY;AqVW>sKG|z01=F^wQ|lpE z_`qKI-0AR%q+8I;;g_cborT +tf2WW_3H_`|P{Cs26}{_p0X3Z~uZx3&>Rp~B zNFZ1AdVkJyJ$r7+?UC(58P<^&53`brCl$(SrF=wouk|#eh$5AvE3gte05}?lC|STH zkjcbC%QK1E%R<=8F-c6LGeG0a&WfOIe!0l6F}i5FW%al9)tBE=zoi76-sYMdJaK_# zEVho}Xo_FKON2Pi@&!OEq=nSntq|Wc@NDRA4#w5Y4Kq-EC1;~;-QsN^$ajIPmI6yz z;bv8ygBw{_VVa#=U*v8?!-t8xpoY~JG9}&ls~|0)`9Ep!Lpjv@63*rmv}wqSuOHzQ zzw1-2BQoza)ysq_bdwU%C1lqrTlKcOUwj$KCjA-l*nuw$`AVR^PI*nduK(eQt}dqI zA*hif^bq-Qu0*B#V*`=eMSYxDWY~by`kkl8{4dC_T?JX(A5O9J*n9K7uPkfvGjpH- z;{pR@`{f7dTP_Uw#Qq%~BD!@Aq;zyIYTLa3zZfK6?K27)8ClbCTMjla=fMuf$`cm- z2v%JsX`6+&D*=ed;a`|GGwJ;m6Mq3AuFsgGH`h|R96;Ad)}fcMM>CkNn@GgCekc}Z zw{5_Nx5sWPQp09Bg0O$y!;#fLf=r*`Bls%6{OODmo3cYd9l#@+E(uBa?~Zk+JqNCV z(vTGjNb?^nDgInb>D)ak+v{gJCnwT>Wx&i4I5IwhNU5|G3v?eV`!0DcVAF1qT7_^O z$H`^ePW=m9 (rm|A%*0!TeOaKo27aEL+? zX|TaVLQbv{z?Rnr ~D*;sJIrFBNXd`L#vN~T06e2=j!@kwu`;_EA?jyoRz^N3M+&_ps#0>%+J#yRTl zy3Zx?hLcPPtF#U&jCMX~q1Ew)-u1ai;d2rcXn;By`D+}o Ix1o<#Pkn5V Uq6M&6_k!&za56+_U7_UKm1 zs3usWn4FG%yz)g*mH=Y{By47f%O|DhEQrk2ql+8kXhLpimpu4@smgo 67Y7v2O_`ud2-D7#F5`Bvwna--=MmX@VJ6UAaVn0wqT`1)swTY^t6GXs>%eOj zXa`Z&fZeGCaas8bMiD=Krb1abz2G&I=@ec1TFZSsqq!KL6L{9v-1?PfFe9=<`(M?r zLiu0EcT5z~nV`xzz8$Y !>TR+(0qGMfi-8A{f-9Jq+pB+&4DUsQ6#jC z5zT!R6k5KEfof|4Zy|Y>P}Y_=gvh^MnSP{K(ukyYU)eH_*Z~<_g4YWfVD!mH#D+py zg<;%zTih}C67=St)%zKg)LwE_=4W SQ4LVtoh5zr~&MNZ?pVx^Wz6V `1uYA_o2T{x z@ZJ{#Di>Zu&a9U{B5GoxQaJ3GN1Y{qzDE~0?e{NuK{!Rb9#uN{P_2SQXPgZLxgQL^ z!k(;tU=KH7LIw5Pn>Jm)uxor^$DXO>hr83@kj#a0g_8kq;NoF0gqr9}P`}-r9Ps5M zE75C{`uVs-@yFdLI^aX}YM8jW0n+YS7i?mkH9V%x_e+R~;ve?d&OP>UxAO% y28d*A9>?>Qy{ZR)UaYA6+VERPAwjiAF=)vA%{UJ z5ey>r8i~3@!+FFA5x3az_?iQnqSG|gUFFk($5U3{CLB~L?+*amgA+R8%g5D$aF|gl z4B&GLe|Rl`{c;vE??wwKcFns$z8%8ZY>}Evx=84q0Er|<%AS{bQv)`qKTQJg-!d!6 zq #|#kIUuzyT%HBO_}NVWdDFrQH vG LDzp}}q zV2N9;m~3}$z`H6_@tf&f$y-b0N~b33y7=LW3^_0eG&oSyY*hA2GWX;k+`7p=$_5jb z*t{bKLT2@NciBoy7WV`h7)isr|0xb^ExY)1AZ|d025H3+KT|7%|3F$A2m#4J() t L-Tz)lCrCgG^h z&r=?b*n@z~2?Qn*UJmA@Z^Ilz?1&BVm$W<8cq}T&|I{%tg?a|6^$Ve4zUoPjVIiXQ zf{-1bj5s$lAKyk_Nlp0`^RcOiR9CpqnLn`2%mSipSpG-tNo1Y<2Tt9n{?5xvh)opv zFW`cT41GMpHw;?lC}ce|dtGWX!DbGHrXx=O`7Odc8LJ0dAI+1;lpISeeHqa4@7u_? zHz2L`H0}(68*IeC 3QX*T46_ul=yM=*l;XU@@GHt? H(e;VYqc_tIcf1e+a|I(dis(3Acx~xxK-?;i9)Zv6;pErpH zs4;0-N#A^YQ@>{c85n=iz(hv;Vpk~J%mF*gYTMPjoTrXI+({vrr$B X4sZSF*Do6RQ*qO#3 z>>T37VR_kWu?7B1x6Y24{2-vz^%*Sg|6SWo1b6F?)>xDaTWS#?c=+UP7`vVuvZFGa z)o~^J!=;~f)F!R;29S{S;Pupha{ )!~a@RmSSK?}LRRFTXR$`xp%@He@K4 z=q$J(yQRn8HDKt5%(On}adrbJv bG+7P+8KBHoZ(BTh`YnEOCJ`b@W!oMi!`Q&c81}vL+r!{2& zBIm+RHR1HO;i%0p<3WI)0cInVAC|$=O@!=d&b9|nAHuK7@P1ny+q)h3IFB*a$6{u!cN?m4I4Z0E!gwCUurF(bmR!t=2HWJ!RJoAkBi6V zJ+jv6nt?&K_&?D+h9Ck>ppokHV}{4+iC}3D=r@jRc;bh kt zT#&s1D|DHzCdZ{24y^9~lGZV>{l|F>;_`42YR2G=5Wrvp*XD}cf5jJQN+)9EB+G!s zYwankGC?ub+`=o_QTCW5HhyckrYi6%c0o9~Ot`psV~{Tsto)KIS>tg3IyBnPdi-^f zUlE5x=Y#J_aHY#%UqH3G?5ukW#o>7;_*9G r-%7Q6P`Vb|!se}5JE zYH&<|jB5rB9N8J26N}%Qt@FlpGT(X0;sM?xJ%riA4oQSEtCK^9kNrv957qBM=wIbp zKv8wmrFok?9RYAWz?(=5c`cj)uhkKni0UZ=}tdY+w7C>76NupMl7uCdOM41N#H- zU=rkK^M?nr@zoEY+;KX1_8h-xx%z|4Q|#@mk72mpPb1kJjZ#tG4|PeKsm26$fRwGv z-Iu5iOX~Sv+S-hszdVr&uZ>Qs57~RbEtSWs%y-g!KvgD3g<$&ghx^MPIvMgkrneqx zZpD0?Z$C+A6+LR=G>9b`qIt{l!hA?aS^TVL*AvB)Qznm{><@mbj6;P<-fs#>cEDz7 z-xHG?EG>a;&~|F~Se>jGzp%Rd46Iq|zMK4pb(kjUyCm?05hbY}J86aD6P!;qnjJe) zBiRRvU;PxNN<|IMOJwic(`f!p6Jg*Rqk(BO{Lst0NLp;Dv>Lzr+%Cys8uWHJeJjs; zJH3{W#<^n->+RCqZcJGsi%mFxd^g|KA87yvm$;8PUVROjJ;>Nx<>#+fm7q$}SL5Ll zR6)m|h0d$hkh%Mns B(zu=RUrguR`g-OX>a0FO>{(8yl=4&8&A-(I|{=N*Ia9wC(9yjL&~F?IjjWXUPn z?4TKPuDWaewDT+VylQxyvA;5E`TXR(f&GDB%(PQCF8t|Bja_R8*IRngb@dn3Ca&Gw zq&TiN<0b#y8FQI9v7mRe3*NkcD*zAKe1FpLDBwAFE%k)kK