From 6aa675e3ef71c50dddd7d787209d17f42df34a75 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Thu, 8 Oct 2026 08:44:47 +1300 Subject: [PATCH] Update docs --- CONTRIBUTING.md | 6 +++--- app/config.json | 6 ++++-- docs/config/error-responses.md | 4 ++-- docs/config/gallery.md | 2 +- docs/config/ipp-options.md | 2 +- docs/troubleshooting.md | 8 +++++--- upload-app/src/index.ts | 7 +++++-- 7 files changed, 21 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5489073..fb4e58c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,7 +31,7 @@ Request flow for a typical share URL like `https://proxy.example.com/share/ The repo is an npm workspace with three packages: `shared/` is `@ipp/core`, the read-side code both apps share; `app/` is IPP itself; and `upload-app/` is the optional upload service, the only code that writes to Immich. Run `npm install` at the root; there is one lockfile. ``` -.github/workflows/ CI: builds and pushes Docker image on v* tags +.github/workflows/ ci.yaml builds and pushes both Docker images on v* tags; docs.yaml deploys the docs site package.json Workspace root: scripts that delegate to the workspaces; no dependencies package-lock.json The one lockfile for every workspace .eslintrc Lint config for every workspace @@ -168,7 +168,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 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. +**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. Rename a key only in a major version: the old name simply stops being read (no compatibility shim), and the rename gets a row in Renamed config keys (`docs/config/upgrading.md`) plus a line in that release's upgrade notes. **Privacy of responses.** Always return 404 for invalid or upstream-failed requests. Use `respondToInvalidRequest` from `@ipp/core` rather than crafting ad-hoc error responses; it calls IPP's `invalidRequestHandler`, which index.ts registers at startup. Do not surface Immich status codes or error bodies to the client. @@ -232,7 +232,7 @@ If you are an AI coding agent working on this repo, the rules above apply to you - **Read this whole file before suggesting or making changes.** The read-only, lean, stateless constraints are project-defining and must not be relaxed for convenience. - **Do not suggest features from the "will not be accepted" list**, even if they are technically interesting. Push back on requests that would violate the constraints, and explain why. -- **Do not add backwards-compatibility shims** unless a config key is being renamed or a public behavior is changing. Dead-code shims rot. +- **Do not add backwards-compatibility shims.** Config keys are renamed only in a major version and the old name stops being read; document the rename instead. Dead-code shims rot. - **Do not add caches, memoization, queues, or background jobs** without first estimating the real cost of not having them. The existing share-metadata cache in `immich.ts` is for freshness coalescing, not optimisation; mirror that bar. - **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*. diff --git a/app/config.json b/app/config.json index 89c25c6..d802e5e 100644 --- a/app/config.json +++ b/app/config.json @@ -35,7 +35,8 @@ "city": false, "state": false, "country": false, - "gps": false + "gps": false, + "webLink": true } }, "customInvalidResponse": false, @@ -56,7 +57,8 @@ "showArrows": true, "showDownload": true, "mobileArrows": false, - "autoPlayVideos": false + "autoPlayVideos": false, + "options": {} } } } diff --git a/docs/config/error-responses.md b/docs/config/error-responses.md index c699745..5c2e675 100644 --- a/docs/config/error-responses.md +++ b/docs/config/error-responses.md @@ -4,7 +4,7 @@ To avoid giving information away about your server, IPP responds with a limited | Code | Reason | |------|-------------------------------------------------------------------------------------------------| -| 503 | Healthcheck failed: Immich is not accessible. Only on the `/healthcheck` route. | +| 503 | Healthcheck failed: Immich is not accessible. Only on `/share/healthcheck` (and the older `/healthcheck`). | | 401 | Invalid password provided for a password-protected share link. | | 204 | No upload service at `/upload/healthcheck`. The gallery checks this path before showing the "Add photos" button; see [`uploadUrl`](/config/ipp-options#uploadurl). | | 404 | All other invalid requests, e.g. album doesn't exist, share link is expired, non-existing file. | @@ -24,7 +24,7 @@ If you want to send a custom 404 page, you would do that with either of the belo ## Custom function -You can also write your own function. Take a copy of `app/dist/invalidRequestHandler.js` from the image of the IPP +You can also write your own function. Take a copy of `/app/dist/invalidRequestHandler.js` from the image of the IPP version you run, edit it, and mount it back into the container at the same path. A copy from an earlier major version can fail to load. diff --git a/docs/config/gallery.md b/docs/config/gallery.md index 52e497b..19da3ca 100644 --- a/docs/config/gallery.md +++ b/docs/config/gallery.md @@ -72,7 +72,7 @@ Language for the [`showExpiryDate`](#showexpirydate) date when the format uses n Group the gallery's thumbnails by date, with a header above each group. - `false` - no grouping (default). -- `"month"` - month headers like "December 2024". +- `"month"` - month headers like "December 2024". `true` means the same. - `"day"` - day headers like "Wed, 25 Dec 2024" (matching Immich's own timeline format). Grouping uses the date each photo was taken, as in Immich's own timeline. Groups follow the album's sort order in Immich, and newest first for shares without one. Photos with no date go under an "Undated" header at the end. diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index c510395..3def877 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -55,7 +55,7 @@ Highest quality the lightbox loads when you zoom in past fit-to-screen. `"original"` is not an option here, because an original can be a RAW or DNG file the browser cannot display. -This setting is independent of [`allowDownload`](#allowdownload): the download buttons can be off while zoom is on. The full-resolution image is only available when the share's own "Allow downloads" toggle in Immich is on, and the photo is a JPEG, PNG or WebP. For other formats, or shares with downloads off in Immich, the lightbox stays on the preview. To get full-resolution zoom without showing download buttons, leave downloads on in Immich and set [`allowDownload`](#allowdownload) to `0`. +This setting is independent of [`allowDownload`](#allowdownload): the download buttons can be off while zoom is on. The full-resolution image is only available when the share's own "Allow downloads" toggle in Immich is on; with it off, the lightbox stays on the preview. For a JPEG, PNG or WebP the zoom loads the original file. For other formats (RAW, HEIF, ...) it loads Immich's converted full-size image, which exists only if full-size previews are enabled in Immich's image settings; otherwise Immich serves the preview. To get full-resolution zoom without showing download buttons, leave downloads on in Immich and set [`allowDownload`](#allowdownload) to `0`. ## `motionPhotos` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 7fd5afa..5727e9e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -85,10 +85,11 @@ If IPP can't connect to Immich even though the container clearly can, you'll see ``` 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. +From the container IPP is running in, run this and check you receive a JSON result: node -e "fetch('http://immich_server:2283/api/server/ping').then(r => r.text()).then(console.log).catch(console.error)" +Avoid testing with curl - curl uses its own DNS resolver and can succeed even when the resolver Node/IPP uses (musl getaddrinfo) fails. ``` -yet running that same `curl` from a shell inside the container succeeds: +yet `curl` from a shell inside the container succeeds: ``` /app $ curl http://immich_server:2283/api/server/ping @@ -99,7 +100,8 @@ This happens with both Docker Compose service names (like `immich_server`) and h (for example an AdGuard Home or dnsmasq CNAME rewrite). The cause is the DNS lookup, not IPP: Node asks for the IPv4 and IPv6 addresses at once, and if your resolver answers the IPv6 query with `NXDOMAIN` instead of an empty `NOERROR`, the Alpine base image fails the whole lookup even though the IPv4 address is fine. `curl` tolerates this, which is why -it works from a shell. The underlying error is `getaddrinfo ENOTFOUND`. +it works from a shell and why the log suggests the `node -e` command instead: it uses the same resolver as IPP, so it +fails the same way. The underlying error 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`: diff --git a/upload-app/src/index.ts b/upload-app/src/index.ts index 382573e..8921a50 100644 --- a/upload-app/src/index.ts +++ b/upload-app/src/index.ts @@ -75,9 +75,12 @@ function bodyDeadline (ms: number): RequestHandler { /* [ROUTE] Healthcheck, reachable at the root whatever the mount prefix, so one - compose healthcheck fits both routing shapes + compose healthcheck fits both routing shapes. */ -app.get(['/healthcheck', '/share/healthcheck'], asyncHandler(healthcheck)) +app.get(['/healthcheck', '/share/healthcheck'], (_req, res, next) => { + addNoStoreHeaders(res) + next() +}, asyncHandler(healthcheck)) const router = Router()