Update docs

This commit is contained in:
Alan Grainger
2026-10-07 16:48:30 +13:00
parent 9ad99cb91b
commit ba893dc42f
8 changed files with 19 additions and 14 deletions
+4 -4
View File
@@ -62,7 +62,7 @@ app/
index.ts Express setup and routes index.ts Express setup and routes
immich.ts Share lookup with album enumeration and cache, asset detail, IPP URLs immich.ts Share lookup with album enumeration and cache, asset detail, IPP URLs
invalidRequestHandler.ts IPP's 404 handler; operators may replace the compiled file by a mount invalidRequestHandler.ts IPP's 404 handler; operators may replace the compiled file by a mount
share.ts Share-level policy (canDownload, expiry date, motion photos) share.ts Share-level policy (canDownload, expiry date, motion photos, upload link and probe)
types.ts Gallery-only server types types.ts Gallery-only server types
version.ts Release version and the static-asset cache-busting segment version.ts Release version and the static-asset cache-busting segment
gallery/ gallery/
@@ -83,8 +83,8 @@ app/
upload-app/ immich-public-proxy-upload - one page per share; streams visitor files to Immich's POST /assets upload-app/ immich-public-proxy-upload - one page per share; streams visitor files to Immich's POST /assets
config.json Default ipp.upload.* options; no responseHeaders config.json Default ipp.upload.* options; no responseHeaders
src/ src/
index.ts Express setup and routes, mounted under PUBLIC_BASE_URL's path index.ts Express setup and routes, served both under /upload and at the root
config.ts Env and ipp.upload.* readers, base path config.ts Env and ipp.upload.* readers
share.ts Share lookup through core, cached 60 s share.ts Share lookup through core, cached 60 s
gate.ts The upload permit: the share's Immich toggle and the slug-link gate gate.ts The upload permit: the share's Immich toggle and the slug-link gate
receive.ts Validates one upload request: rate limit, length, filename, type, byte budget receive.ts Validates one upload request: rate limit, length, filename, type, byte budget
@@ -162,7 +162,7 @@ npm run test:watch # vitest in watch mode
npm run test:container # build a podman image and run it locally npm run test:container # build a podman image and run it locally
``` ```
`npm test` runs the pure-function unit tests in `shared/tests/` and `app/tests/`. IPP's tests import `@ipp/core` from its source, so they need no build. Today the suite covers `escapeHtml` only; the other shipped pure-function areas (filename derivation, layout math, EXIF whitelisting) deserve coverage too. Add tests as you touch those areas, and for any new pure logic you introduce. Skip HTTP plumbing. `npm test` runs the pure-function unit tests in `shared/tests/`, `app/tests/` and `upload-app/tests/`. The apps' tests import `@ipp/core` from its source, so they need no build. Add tests as you touch a pure-function area, and for any new pure logic you introduce. Skip HTTP plumbing.
Beyond unit tests, exercise the gallery end-to-end against a real Immich instance: happy path plus failure paths (expired share, trashed asset, password protection, very large albums, video range requests). Beyond unit tests, exercise the gallery end-to-end against a real Immich instance: happy path plus failure paths (expired share, trashed asset, password protection, very large albums, video range requests).
+2 -1
View File
@@ -50,4 +50,5 @@ The JSON config as an inline string. When set, no config file is read at all. Se
`APP_VERSION` and `NODE_ENV` are set by the Docker image and are not meant to be changed. `APP_VERSION` and `NODE_ENV` are set by the Docker image and are not meant to be changed.
The optional upload service has its own variables. See [Upload service](/config/upload-service#environment-variables). The optional upload service reads the same variables, with the same meanings, so the `environment` block can be
copied across. See [Upload service](/config/upload-service#environment-variables).
+1
View File
@@ -6,6 +6,7 @@ To avoid giving information away about your server, IPP responds with a limited
|------|-------------------------------------------------------------------------------------------------| |------|-------------------------------------------------------------------------------------------------|
| 503 | Healthcheck failed: Immich is not accessible. Only on the `/healthcheck` route. | | 503 | Healthcheck failed: Immich is not accessible. Only on the `/healthcheck` route. |
| 401 | Invalid password provided for a password-protected share link. | | 401 | Invalid password provided for a password-protected share link. |
| 204 | Nothing is routed to the upload service's healthcheck path, `/upload/healthcheck` by default. The gallery probes it 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. |
Instead of sending the 404 code, you can customise that response by [changing the configuration option](/config/ipp-options#custominvalidresponse) for `customInvalidResponse`. Instead of sending the 404 code, you can customise that response by [changing the configuration option](/config/ipp-options#custominvalidresponse) for `customInvalidResponse`.
+1 -1
View File
@@ -1,7 +1,7 @@
# Configuration # Configuration
> [!TIP] > [!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. > 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), and the upload service's in [its own config.json](https://github.com/alangrainger/immich-public-proxy/blob/main/upload-app/config.json). A description of each option is on the pages in this section.
Connection settings (the Immich URL, public URL, port and config file location) are 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: [environment variables](/config/environment-variables). Everything else is JSON config under `ipp.*`, grouped into:
+1 -1
View File
@@ -110,7 +110,7 @@ The bulk-zip and per-asset buttons can be toggled independently once downloads a
Where the optional upload service (the `immich-public-proxy-upload` container) is served. A share whose "Allow public user to upload" option is on in Immich then shows an "Add photos" button in the gallery header, which opens that share's page on the upload service. To set up the service, see [Let visitors send photos back](/visitor-uploads). Where the optional upload service (the `immich-public-proxy-upload` container) is served. A share whose "Allow public user to upload" option is on in Immich then shows an "Add photos" button in the gallery header, which opens that share's page on the upload service. To set up the service, see [Let visitors send photos back](/visitor-uploads).
- **A path**, such as the default `/upload`, means the service is on IPP's own hostname under that path. Before showing the button, the gallery page checks that something answers at `<path>/healthcheck`, so an install without the upload container never shows a dead button. - **A path**, such as the default `/upload`, means the service is on IPP's own hostname under that path. Before showing the button, the gallery page checks that the upload service answers `ok` at `<path>/healthcheck`, so an install without the upload container never shows a dead button. When nothing is routed there, IPP answers that path itself with an empty 204 rather than a 404, so the check is neither a browser console error nor a hit on the [404 policy](/config/error-responses).
- **An absolute URL**, such as `https://upload.example.com`, means the service has a hostname of its own. It is trusted without a check. The URL may include a path, such as `https://photos.example.com/upload`, which points at the same place as the default but without the check. - **An absolute URL**, such as `https://upload.example.com`, means the service has a hostname of its own. It is trusted without a check. The URL may include a path, such as `https://photos.example.com/upload`, which points at the same place as the default but without the check.
- **An empty string** never shows the button. - **An empty string** never shows the button.
+5 -3
View File
@@ -57,7 +57,8 @@ A reverse proxy or CDN in front of the service can have a lower limit of its own
**Type:** `int` · **Default:** `60` **Type:** `int` · **Default:** `60`
Files accepted per minute from one visitor address to one share. Over the limit, the service answers with the time to Files accepted per minute from one visitor address to one share. Over the limit, the service answers with the time to
wait, and the page sends the file again after it. `0` turns the limit off. wait, and the page sends the file again after it, up to three tries. A wait of more than a minute is shown as a
failure with a retry button instead. `0` turns the limit off.
The address is the one that connects to the service. Behind a reverse proxy every visitor has the proxy's address, so The address is the one that connects to the service. Behind a reverse proxy every visitor has the proxy's address, so
the limit covers each share as a whole. the limit covers each share as a whole.
@@ -146,7 +147,8 @@ The service also reads two IPP options, with the same meaning:
- [`customInvalidResponse`](/config/ipp-options#custominvalidresponse). The status code, redirect, `null` and `false` - [`customInvalidResponse`](/config/ipp-options#custominvalidresponse). The status code, redirect, `null` and `false`
forms all apply. There is no `invalidRequestHandler.js` to replace in the upload image. forms all apply. There is no `invalidRequestHandler.js` to replace in the upload image.
`responseHeaders` is not read. Every response from the service carries `Cache-Control: no-store` and no CORS header. `responseHeaders` is not read. Every response from the service other than its static assets carries
`Cache-Control: no-store`, and none carries a CORS header.
## Refused uploads ## Refused uploads
@@ -159,7 +161,7 @@ one of these codes and a short reason, which the page shows to the visitor:
| 400 | The filename has no extension, or Immich refused the file, for example because the owner's storage quota is full. | | 400 | The filename has no extension, or Immich refused the file, for example because the owner's storage quota is full. |
| 403 | The share no longer accepts uploads. | | 403 | The share no longer accepts uploads. |
| 411 | The request has no `Content-Length` header. | | 411 | The request has no `Content-Length` header. |
| 413 | The file is larger than `maxFileSize`, or the share has used its `byteBudget` for the hour. | | 413 | The file is larger than `maxFileSize`, sent more bytes than its `Content-Length` declared, or the share has used its `byteBudget` for the hour. |
| 415 | The file is not a photo or a video. SVG files are refused. | | 415 | The file is not a photo or a video. SVG files are refused. |
| 429 | The visitor is over `rateLimit`. `Retry-After` gives the wait in seconds. | | 429 | The visitor is over `rateLimit`. `Retry-After` gives the wait in seconds. |
| 502 | Immich could not be reached, or failed. | | 502 | Immich could not be reached, or failed. |
+1 -1
View File
@@ -27,7 +27,7 @@ version. Breaking changes and renamed config keys land in major versions and are
load. See [Custom function](/config/error-responses#custom-function). load. See [Custom function](/config/error-responses#custom-function).
Visitor uploads are new in 4.0. An existing install is not affected until you add the upload service: IPP looks for Visitor uploads are new in 4.0. An existing install is not affected until you add the upload service: IPP looks for
it at `/upload` on its own hostname and shows the "Add photos" button only when something answers there. See it at `/upload` on its own hostname and shows the "Add photos" button only when the upload service answers there. See
[Let visitors send photos back](/visitor-uploads). [Let visitors send photos back](/visitor-uploads).
### Compose file ### Compose file
+4 -3
View File
@@ -26,13 +26,13 @@ read-only.
**No API key is required.** **No API key is required.**
<img src="/visitor-uploads.svg" width="900" height="660" alt="How visitor uploads work: the browser reaches the reverse proxy, which sends gallery requests to the read-only immich-public-proxy container and /upload requests to the optional immich-public-proxy-upload container. Both talk to Immich with the visitor's share key. Immich refuses uploads unless the share allows them, stores the file and adds it to the album or link."> <img src="./public/visitor-uploads.svg" width="900" height="660" alt="How visitor uploads work: the browser reaches the reverse proxy, which sends gallery requests to the read-only immich-public-proxy container and /upload requests to the optional immich-public-proxy-upload container. Both talk to Immich with the visitor's share key. Immich refuses uploads unless the share allows them, stores the file and adds it to the album or link.">
1. In Immich, the owner turns on **Allow public user to upload** for a shared link. The gallery for that share then 1. In Immich, the owner turns on **Allow public user to upload** for a shared link. The gallery for that share then
shows an **Add photos** button. shows an **Add photos** button.
2. A visitor clicks the button. It opens the upload page for the same share on the upload service's separate container. 2. A visitor clicks the button. It opens the upload page for the same share on the upload service's separate container.
3. The upload container streams the file straight to Immich with the share's own key. It stores nothing and holds no API key. 3. The upload container streams the file straight to Immich with the share's own key. It stores nothing and holds no API key.
5. Immich checks that the share still allows uploads, stores the file as if the share owner had uploaded it, and adds 4. Immich checks that the share still allows uploads, stores the file as if the share owner had uploaded it, and adds
it to the share. it to the share.
What the owner sees in Immich: What the owner sees in Immich:
@@ -164,7 +164,8 @@ it cannot.
## Show the button in IPP ## Show the button in IPP
With the upload service on a path on the IPP hostname, there is nothing to set. IPP assumes the service is at With the upload service on a path on the IPP hostname, there is nothing to set. IPP assumes the service is at
`/upload` on its own hostname, and the gallery shows the button once `/upload/healthcheck` answers. `/upload` on its own hostname, and the gallery shows the button once the upload service answers `ok` at
`/upload/healthcheck`.
With a hostname of its own, set [`uploadUrl`](/config/ipp-options#uploadurl) in IPP's config to that URL and restart With a hostname of its own, set [`uploadUrl`](/config/ipp-options#uploadurl) in IPP's config to that URL and restart
IPP: IPP: