From ba893dc42f75174ddc56123a44b9e20fa85dcc2e Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Wed, 7 Oct 2026 16:48:30 +1300 Subject: [PATCH] Update docs --- CONTRIBUTING.md | 8 ++++---- docs/config/environment-variables.md | 3 ++- docs/config/error-responses.md | 1 + docs/config/index.md | 2 +- docs/config/ipp-options.md | 2 +- docs/config/upload-service.md | 8 +++++--- docs/upgrading.md | 2 +- docs/visitor-uploads.md | 7 ++++--- 8 files changed, 19 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9590c02..5489073 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,7 +62,7 @@ app/ index.ts Express setup and routes 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 - 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 version.ts Release version and the static-asset cache-busting segment gallery/ @@ -83,8 +83,8 @@ app/ 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 src/ - index.ts Express setup and routes, mounted under PUBLIC_BASE_URL's path - config.ts Env and ipp.upload.* readers, base path + index.ts Express setup and routes, served both under /upload and at the root + config.ts Env and ipp.upload.* readers share.ts Share lookup through core, cached 60 s 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 @@ -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 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). diff --git a/docs/config/environment-variables.md b/docs/config/environment-variables.md index d8ead6f..4b8ee8b 100644 --- a/docs/config/environment-variables.md +++ b/docs/config/environment-variables.md @@ -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. -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). diff --git a/docs/config/error-responses.md b/docs/config/error-responses.md index d765553..74bdcf1 100644 --- a/docs/config/error-responses.md +++ b/docs/config/error-responses.md @@ -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. | | 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. | Instead of sending the 404 code, you can customise that response by [changing the configuration option](/config/ipp-options#custominvalidresponse) for `customInvalidResponse`. diff --git a/docs/config/index.md b/docs/config/index.md index 3b42da7..e88d1eb 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -1,7 +1,7 @@ # 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. +> 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 [environment variables](/config/environment-variables). Everything else is JSON config under `ipp.*`, grouped into: diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index 68f93a9..e8ddbc9 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -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). -- **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 `/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 `/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 empty string** never shows the button. diff --git a/docs/config/upload-service.md b/docs/config/upload-service.md index 9ae42ec..e13c96f 100644 --- a/docs/config/upload-service.md +++ b/docs/config/upload-service.md @@ -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` 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 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` 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 @@ -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. | | 403 | The share no longer accepts uploads. | | 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. | | 429 | The visitor is over `rateLimit`. `Retry-After` gives the wait in seconds. | | 502 | Immich could not be reached, or failed. | diff --git a/docs/upgrading.md b/docs/upgrading.md index f02467d..6fc435c 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -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). 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). ### Compose file diff --git a/docs/visitor-uploads.md b/docs/visitor-uploads.md index b84a5a0..0f851df 100644 --- a/docs/visitor-uploads.md +++ b/docs/visitor-uploads.md @@ -26,13 +26,13 @@ read-only. **No API key is required.** -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. +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 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. 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. What the owner sees in Immich: @@ -164,7 +164,8 @@ it cannot. ## 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 -`/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 IPP: