Update docs
This commit is contained in:
+3
-3
@@ -31,7 +31,7 @@ Request flow for a typical share URL like `https://proxy.example.com/share/<key>
|
|||||||
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.
|
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.json Workspace root: scripts that delegate to the workspaces; no dependencies
|
||||||
package-lock.json The one lockfile for every workspace
|
package-lock.json The one lockfile for every workspace
|
||||||
.eslintrc Lint config 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
|
## 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.
|
**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.
|
- **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 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 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).
|
- **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*.
|
- **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*.
|
||||||
|
|||||||
+4
-2
@@ -35,7 +35,8 @@
|
|||||||
"city": false,
|
"city": false,
|
||||||
"state": false,
|
"state": false,
|
||||||
"country": false,
|
"country": false,
|
||||||
"gps": false
|
"gps": false,
|
||||||
|
"webLink": true
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"customInvalidResponse": false,
|
"customInvalidResponse": false,
|
||||||
@@ -56,7 +57,8 @@
|
|||||||
"showArrows": true,
|
"showArrows": true,
|
||||||
"showDownload": true,
|
"showDownload": true,
|
||||||
"mobileArrows": false,
|
"mobileArrows": false,
|
||||||
"autoPlayVideos": false
|
"autoPlayVideos": false,
|
||||||
|
"options": {}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ To avoid giving information away about your server, IPP responds with a limited
|
|||||||
|
|
||||||
| Code | Reason |
|
| 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. |
|
| 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). |
|
| 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. |
|
| 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
|
## 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 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.
|
version can fail to load.
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
Group the gallery's thumbnails by date, with a header above each group.
|
||||||
|
|
||||||
- `false` - no grouping (default).
|
- `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).
|
- `"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.
|
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.
|
||||||
|
|||||||
@@ -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.
|
`"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`
|
## `motionPhotos`
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
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
|
/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
|
(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`,
|
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
|
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
|
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`:
|
your service in `docker-compose.yml`:
|
||||||
|
|||||||
@@ -75,9 +75,12 @@ function bodyDeadline (ms: number): RequestHandler {
|
|||||||
|
|
||||||
/*
|
/*
|
||||||
[ROUTE] Healthcheck, reachable at the root whatever the mount prefix, so one
|
[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()
|
const router = Router()
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user