From 20c4238b6ef74422d60d4861a4c2578a7fde3f2a Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Tue, 6 Oct 2026 15:17:11 +1300 Subject: [PATCH] Update docs --- CONTRIBUTING.md | 10 +- README.md | 13 +- docs/.vitepress/config.ts | 2 + docs/config/environment-variables.md | 2 + docs/config/index.md | 3 +- docs/config/ipp-options.md | 2 + docs/config/upload-service.md | 169 ++++++++++++++++++ docs/how-to-use.md | 4 + docs/installation.md | 5 +- docs/introduction.md | 15 +- docs/upgrading.md | 7 + docs/visitor-uploads.md | 255 +++++++++++++++++++++++++++ 12 files changed, 478 insertions(+), 9 deletions(-) create mode 100644 docs/config/upload-service.md create mode 100644 docs/visitor-uploads.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 300bef2..9590c02 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,8 @@ Immich Public Proxy (IPP) exists to share Immich photos publicly without exposin **Read-only access to Immich. This is non-negotiable.** IPP must never modify Immich, its data, or its files. It does not use an Immich API key. The only Immich endpoints it calls are the ones reachable via a public share key. This rule rules out a large class of feature requests; see "What will not be accepted" below. +**The one write path lives in its own image.** Visitor uploads are the single exception, and they live in `upload-app/` (the `immich-public-proxy-upload` image), which operators add only if they want it. The upload service writes with the visitor's share key, so Immich enforces the share's "Allow public user to upload" toggle; it still has no API key and no state, and its only Immich write is `POST /assets` in `upload-app/src/forward.ts`. `app/` and `@ipp/core` stay read-only: no code that accepts a file or writes to Immich goes there. + **Stateless.** No database, no user accounts, no long-lived secrets beyond an encrypted cookie session for share passwords. Avoid adding persistent state. If you think you need a cache, estimate the real cost of not having it first. **Privacy at the boundary.** Any invalid, expired, or upstream-failed request returns 404. Do not leak upstream Immich status codes, error bodies, or share existence to the client. @@ -198,8 +200,8 @@ Releases are triggered by pushing a `v*` tag. The `.github/workflows/ci.yaml` wo Maintainer workflow for a release: -1. Update `app/package.json` version with `npm version ` from inside `app/`. -2. Push the resulting tag. CI does the rest. +1. Run `npm run bump -- ` at the root. It sets the version in every workspace manifest and the lockfile. +2. Commit, tag `v` and push the tag. CI does the rest. Do not push tags as part of a PR; releases are cut by the maintainer. @@ -215,9 +217,9 @@ For anything non-trivial, open a [Feature Request discussion](https://github.com Repeating the README's feature-request guidance for emphasis: -- Anything that modifies Immich or its files in any way. +- Anything that modifies Immich or its files in any way, beyond the upload service's one `POST /assets`. - Anything that requires an Immich API key or other privileged access. -- Uploading photos to Immich. +- Code in `app/` or `@ipp/core` that accepts a file or writes to Immich. That belongs in `upload-app/`, and only there. - Persistent state, databases, or user accounts on the IPP side. - Client-side bundlers (Webpack / Rollup / Vite / Parcel) or frontend frameworks (React / Svelte / Vue / Solid). Client code is TypeScript compiled file-for-file by `tsc` to plain ES modules served directly - no bundling, no framework runtime, no plugin ecosystem. - Features that meaningfully expand the proxy's attack surface for a niche use case. diff --git a/README.md b/README.md index 997823d..5d54506 100644 --- a/README.md +++ b/README.md @@ -47,13 +47,21 @@ If you use Cloudflare, set your `/share/video/*` path to Bypass Cache or videos Full instructions, including Kubernetes: **[Installation](https://docs.ipp.nz/installation)**. +### Let visitors send photos back + +Visitors can add their own photos and videos to a share, for example guests at a wedding. This needs a second, +optional container, `immich-public-proxy-upload`, and the "Allow public user to upload" option on the share in Immich. +The IPP container itself stays read-only. See +**[Let visitors send photos back](https://docs.ipp.nz/visitor-uploads)**. + ## Documentation Everything is at **[docs.ipp.nz](https://docs.ipp.nz)**: - [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), +- Guides: [let visitors send photos back](https://docs.ipp.nz/visitor-uploads), + [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) @@ -64,4 +72,5 @@ You can [add feature requests here](https://github.com/alangrainger/immich-publi however my goal with this project is to keep it as lean as possible. 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. +require storing a share key won't be considered. Visitor uploads are the one write path, and they live in their own +optional container. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full list. diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index fa4b648..efc7d68 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -52,12 +52,14 @@ export default defineConfig({ { text: 'Lightbox', link: '/config/lightbox' }, { text: 'Metadata', link: '/config/metadata' }, { text: 'Error responses', link: '/config/error-responses' }, + { text: 'Upload service', link: '/config/upload-service' }, { text: 'Renamed config keys', link: '/config/upgrading' } ] }, { text: 'Guides', items: [ + { text: 'Let visitors send photos back', link: '/visitor-uploads' }, { 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' } diff --git a/docs/config/environment-variables.md b/docs/config/environment-variables.md index 3633864..d8ead6f 100644 --- a/docs/config/environment-variables.md +++ b/docs/config/environment-variables.md @@ -49,3 +49,5 @@ The JSON config as an inline string. When set, no config file is read at all. Se [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. + +The optional upload service has its own variables. See [Upload service](/config/upload-service#environment-variables). diff --git a/docs/config/index.md b/docs/config/index.md index bb91076..3b42da7 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -6,11 +6,12 @@ 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: -- [General options](/config/ipp-options) - downloads, zoom quality, slug links, response headers. +- [General options](/config/ipp-options) - downloads, zoom quality, slug links, the upload link, 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. +- [Upload service](/config/upload-service) - the optional container that lets visitors send photos back. - [Renamed config keys](/config/upgrading) - old keys and their current names. ## How to provide a config override diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index cdd4c2d..376c016 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -110,6 +110,8 @@ The bulk-zip and per-asset buttons can be toggled independently once downloads a The public URL of the optional upload service (the `immich-public-proxy-upload` container), for example `https://upload.example.com`. When it is set, a share whose "Allow public user to upload" option is on in Immich shows an "Add photos" button in the gallery header. The button opens that share's page on the upload service. Leave it empty to show no button. +The value is the same as the upload service's [`PUBLIC_BASE_URL`](/config/upload-service#public-base-url). To set up the service, see [Let visitors send photos back](/visitor-uploads). + ## `allowSlugLinks` **Type:** `bool` · **Default:** `true` diff --git a/docs/config/upload-service.md b/docs/config/upload-service.md new file mode 100644 index 0000000..1282f57 --- /dev/null +++ b/docs/config/upload-service.md @@ -0,0 +1,169 @@ +# Upload service + +Settings for the optional upload service, the `immich-public-proxy-upload` container, which lets visitors send photos +and videos back to a share. The setup is in [Let visitors send photos back](/visitor-uploads). + +The service reads config the same way as IPP: a `config.json` mounted at `/app/config.json`, the file named by +`IPP_CONFIG`, or the `CONFIG` environment variable. Its own options are under `ipp.upload.*`. IPP never reads those, +and the service reads none of IPP's options except the two under [Shared options](#shared-options), so one +`config.json` can be mounted into both containers. + +## Example + +Accept files up to 2 GB, and send a notification to a Gotify server for each stored file: + +```json +{ + "ipp": { + "upload": { + "maxFileSize": 2048, + "notifyUrl": "https://gotify.example.com/message?token=YOUR_APP_TOKEN" + } + } +} +``` + +## Environment variables + +`IMMICH_URL`, `IPP_PORT`, `IPP_CONFIG` and `CONFIG` mean the same as for IPP; see +[Environment variables](/config/environment-variables). `IMMICH_URL` is required. The service has two more: + +### `PUBLIC_BASE_URL` + +**Required** + +The public URL of the upload service, for example `https://upload.example.com`. If it includes a path, such as +`https://photos.example.com/upload`, the service serves its pages under that path, and the reverse proxy must forward +the path unchanged. The healthcheck is served at `/healthcheck` at the root as well, so a container healthcheck works +either way. + +### `GALLERY_URL` + +**Optional** + +The public URL of IPP, for example `https://photos.example.com`. When set, the upload page has a back button to the +share's gallery. + +## Options + +### `maxFileSize` + +**Type:** `int` · **Default:** `500` + +The largest single file accepted, in MB. The page refuses a larger file before sending it; the service checks the +declared size on arrival and counts the bytes as they stream. The smallest value is `1`. + +A reverse proxy or CDN in front of the service can have a lower limit of its own. See +[Request size limits](/visitor-uploads#request-size-limits). + +### `rateLimit` + +**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. + +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. + +### `byteBudget` + +**Type:** `int` · **Default:** `10240` + +MB accepted per share per hour, from all visitors together. Each file's declared size is reserved when its upload +starts and released if the upload fails. A file that would exceed the budget is refused until the hour ends. `0` +turns the budget off. + +### `filenamePrefix` + +**Type:** `string` · **Default:** `"ipp_upload_"` + +Added to the start of every stored filename: `IMG_0042.jpg` is stored as `ipp_upload_IMG_0042.jpg`. The prefix is +what an Immich workflow can match on; see [Tag uploaded photos](/visitor-uploads#tag-uploaded-photos). Set it to `""` +to store the visitor's filename unchanged. + +### `notifyUrl` + +**Type:** `string` · **Default:** `""` + +A URL that receives one JSON `POST` for each stored file, sent after the visitor has been answered. Empty means no +notifications. Each notification is sent once, with no retry. A failure is logged with the URL's host only, so a +token in the URL never reaches the log. + +`title` and `message` are at the top level, so Gotify shows them with no setup. Everything else is under `data`: + +```json +{ + "title": "Photo sent to Holiday 2025", + "message": "ipp_upload_IMG_0042.jpg (3.0 MB) was uploaded to Holiday 2025.", + "data": { + "event": "upload", + "time": "2026-10-05T07:18:00.000Z", + "share": { "type": "album", "id": "9f1c…", "title": "Holiday 2025" }, + "file": { "name": "ipp_upload_IMG_0042.jpg", "size": 3145728, "type": "image/jpeg" }, + "asset": { "id": "4b2e…", "status": "created" } + } +} +``` + +- `share.type` is `album` for an album share and `individual` for a share of selected photos. `share.id` is the + album ID or the shared link ID. +- `asset.status` is `created`, or `duplicate` when the owner already had the same file. Immich adds a duplicate to the + share too. +- The body never contains the share key, the custom URL or a password. + +ntfy reads the two fields through its inline templates: + +``` +https://ntfy.sh/your-topic?tpl=yes&t={{.title}}&m={{.message}} +``` + +### `notifyHeaders` + +**Type:** `object` · **Default:** `{}` + +Extra headers sent with each notification, for example an `Authorization` header. Values must be strings. + +```json +{ + "ipp": { + "upload": { + "notifyUrl": "https://hooks.example.com/ipp", + "notifyHeaders": { "Authorization": "Bearer YOUR_TOKEN" } + } + } +} +``` + +### `notifyTimeout` + +**Type:** `int` · **Default:** `10000` + +How long to wait for the notification URL to answer, in milliseconds. + +## Shared options + +The service also reads two IPP options, with the same meaning: + +- [`allowSlugLinks`](/config/ipp-options#allowsluglinks). When `false`, the upload page is not served at `/s/` + either. +- [`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. + +## Refused uploads + +A request for an unknown or expired share, or for a share whose "Allow public user to upload" option is off, gets the +same [error response](/config/error-responses) as it would from IPP. Once a share accepts uploads, a refused file gets +one of these codes and a short reason, which the page shows to the visitor: + +| Code | Reason | +|------|------------------------------------------------------------------------------------------------------------------| +| 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. | +| 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/how-to-use.md b/docs/how-to-use.md index 4f1d26a..3e668d3 100644 --- a/docs/how-to-use.md +++ b/docs/how-to-use.md @@ -24,6 +24,8 @@ The settings on the shared link in Immich are respected: [`allowDownload`](/config/ipp-options#allowdownload) for how IPP's own download buttons interact with it. - **Show metadata.** When it is off, IPP hides the description, EXIF and location data regardless of its own [metadata settings](/config/metadata). +- **Allow public user to upload.** When it is on and you run the optional upload service, the gallery shows an + **Add photos** button. See [Let visitors send photos back](/visitor-uploads). ## What visitors see @@ -39,6 +41,8 @@ The settings on the shared link in Immich are respected: - Photos can be grouped under month or day headers with [`gallery.groupByDate`](/config/gallery#groupbydate). - An info sidebar in the lightbox shows whatever [metadata](/config/metadata) you have chosen to reveal. Nothing is revealed by default. +- When the share accepts uploads, visitors can send their own photos and videos into it with the **Add photos** + button. Try it on the [live demo](https://demo.ipp.nz/s/demo-gallery). diff --git a/docs/installation.md b/docs/installation.md index ba2e7e6..2641b4d 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -43,9 +43,12 @@ Those two variables are all most people need. The port and the config file locat Images are published to Docker Hub (`alangrainger/immich-public-proxy`) and GitHub Container Registry (`ghcr.io/alangrainger/immich-public-proxy`) for `linux/amd64` and `linux/arm64`. Each release is tagged with its -full version (for example `3.3.0`), its minor version (`3.3`) and its major version (`3`), and `latest` always points +full version (for example `4.0.0`), its minor version (`4.0`) and its major version (`4`), and `latest` always points at the newest release. +The optional upload service, `alangrainger/immich-public-proxy-upload`, is published in the same places with the same +version tags. You only need it to [let visitors send photos back](/visitor-uploads). + ### 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 diff --git a/docs/introduction.md b/docs/introduction.md index 03223f0..e542b22 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -47,7 +47,8 @@ with public access only to IPP. See [Securing Immich with mTLS](/securing-immich IPP holds to three rules, which also decide which feature requests are accepted: - **Read-only.** IPP never modifies Immich or its files, and it needs no API key or privileged access. Anything that - would require either will not be added. + would require either will not be added. The one exception, visitor uploads, is a separate container that you add + only if you want it (see [Visitor uploads](#visitor-uploads)). - **Stateless.** No database, no accounts, and no stored share keys. The key in a share URL is what grants access to that share, so anything that would require IPP to remember one is unlikely to be added. - **Small enough to audit.** Because IPP fronts a private photo library, the code stays small enough for someone @@ -57,4 +58,16 @@ Feature requests are welcome in [GitHub Discussions](https://github.com/alangrai with the goal of keeping IPP as lean as possible. [CONTRIBUTING.md](https://github.com/alangrainger/immich-public-proxy/blob/main/CONTRIBUTING.md) lists what will not be accepted. +## Visitor uploads + +Visitors to a share can send photos back to it, but only through a second container, `immich-public-proxy-upload`. +The IPP container has no code that accepts a file or writes to Immich. If you do not run the upload service, no part +of IPP can write to Immich. + +The upload service follows the same rules as IPP in every other way. It needs no API key and keeps no state. It +uploads with the visitor's share key, so Immich itself checks the share's "Allow public user to upload" option on +every file. It never shows anything from your library, and it streams each file to Immich without storing it. + +The setup is in [Let visitors send photos back](/visitor-uploads). + Ready to set it up? Head to [Installation](/installation). diff --git a/docs/upgrading.md b/docs/upgrading.md index 4c6a4ce..e838c65 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -19,9 +19,16 @@ version. Breaking changes and renamed config keys land in major versions and are - **Immich 3.0.0 or newer is required.** Upgrade Immich first. - **Old config keys are no longer read.** Check your `config.json` against [Renamed config keys](/config/upgrading). +- **IPP will not start while the config has `showMetadata.exif.enabled` or `showMetadata.location.enabled`.** Remove + the key, and keep only the per-field flags for what visitors may see. See [Metadata](/config/upgrading#metadata). +- **`allowDownload` takes only `0`, `1` or `2`.** Any other value, such as `true`, now turns downloads off. See + [`allowDownload`](/config/ipp-options#allowdownload). - **A custom `invalidRequestHandler.js` must be copied again from the 4.0 image.** A copy taken from 3.x fails to 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; see +[Let visitors send photos back](/visitor-uploads). + ## Immich version IPP requires **Immich 3.0.0 or newer** and checks the server version at startup. Against an older Immich it logs a diff --git a/docs/visitor-uploads.md b/docs/visitor-uploads.md new file mode 100644 index 0000000..da9536a --- /dev/null +++ b/docs/visitor-uploads.md @@ -0,0 +1,255 @@ +# Let visitors send photos back + +Visitors to a share can send their own photos and videos into it, for example guests adding their pictures to a +wedding album. The photos go straight into the album in Immich and appear in the gallery for everyone. + +Uploads are handled by a second, optional container, `immich-public-proxy-upload`. The IPP container stays +read-only: its only part in this is an **Add photos** button that links to the upload service. Immich decides which +shares accept uploads, through the "Allow public user to upload" option on each shared link. + +This guide assumes IPP is already [installed](/installation) behind a reverse proxy. + +## Contents + +- [What you need](#what-you-need) +- [Add the upload service](#add-the-upload-service) +- [Route it through your reverse proxy](#route-it-through-your-reverse-proxy) +- [Show the button in IPP](#show-the-button-in-ipp) +- [Turn on uploads for a share](#turn-on-uploads-for-a-share) +- [Set a storage quota](#set-a-storage-quota) +- [Request size limits](#request-size-limits) +- [Tag uploaded photos](#tag-uploaded-photos) +- [Get a notification for each upload](#get-a-notification-for-each-upload) +- [Questions](#questions) + +## What you need + +- IPP 4.0 or newer and Immich 3.0.0 or newer. +- A public route to the upload service: its own hostname, such as `upload.example.com`, or a path on the IPP + hostname, such as `photos.example.com/upload`. If a tunnel points straight at IPP with no reverse proxy, add a + second hostname to the tunnel for the upload container. + +## Add the upload service + +Add the service to the `docker-compose.yml` that runs IPP: + +```yaml +services: + immich-public-proxy: + # ... your existing IPP service ... + + ipp-upload: + image: alangrainger/immich-public-proxy-upload:latest + container_name: ipp-upload + restart: always + ports: + - "3001:3000" + environment: + IMMICH_URL: http://your-internal-immich-server:2283 + PUBLIC_BASE_URL: https://upload.example.com + GALLERY_URL: https://photos.example.com + healthcheck: + test: curl -s http://localhost:3000/healthcheck -o /dev/null || exit 1 + start_period: 10s + timeout: 5s +``` + +- `IMMICH_URL` is the same local Immich address that IPP uses. +- `PUBLIC_BASE_URL` is the public URL of the upload service. For a path on the IPP hostname, include the path: + `https://photos.example.com/upload`. +- `GALLERY_URL` is the public URL of IPP. It gives the upload page a back button to the gallery. + +Start it with `docker-compose up -d`. The full list of settings is on [Upload service](/config/upload-service). + +## Route it through your reverse proxy + +Choose one of the two shapes. The examples reach the container as `ipp-upload:3000`, which works when the proxy +shares a Docker network with it. From the host, use the published port instead: `localhost:3001` with the compose +file above. + +### Own hostname + +Send everything on the upload hostname to the upload service. + +Caddy: + +``` +upload.example.com { + reverse_proxy ipp-upload:3000 +} +``` + +nginx: + +```nginx +server { + listen 443 ssl; + server_name upload.example.com; + + client_max_body_size 500m; + proxy_request_buffering off; + + location / { + proxy_pass http://ipp-upload:3000; + } +} +``` + +### Path on the IPP hostname + +Set `PUBLIC_BASE_URL` to the URL with its path, for example `https://photos.example.com/upload`. Forward that path +to the upload service with the path left in place, and everything else to IPP. + +Caddy (`handle` keeps the path; `handle_path` would strip it): + +``` +photos.example.com { + handle /upload/* { + reverse_proxy ipp-upload:3000 + } + handle { + reverse_proxy immich-public-proxy:3000 + } +} +``` + +nginx: + +```nginx +server { + listen 443 ssl; + server_name photos.example.com; + + location /upload/ { + client_max_body_size 500m; + proxy_request_buffering off; + proxy_pass http://ipp-upload:3000; + } + + location / { + proxy_pass http://immich-public-proxy:3000; + } +} +``` + +Check the route by opening `/healthcheck` on the upload URL: `https://upload.example.com/healthcheck` or +`https://photos.example.com/upload/healthcheck`. It answers `ok` when the upload service can reach Immich, and a 503 when +it cannot. + +## Show the button in IPP + +Set [`uploadUrl`](/config/ipp-options#uploadurl) in IPP's config to the upload service's `PUBLIC_BASE_URL`: + +```json +{ + "ipp": { + "uploadUrl": "https://upload.example.com" + } +} +``` + +Restart IPP. One `config.json` can serve both containers: IPP ignores the `ipp.upload.*` keys, and the upload service +reads only those and [two shared options](/config/upload-service#shared-options). + +## Turn on uploads for a share + +In Immich, turn on **Allow public user to upload** for the shared link. The option is in the dialog that creates a +link, and later under **Sharing**, **Shared links**, when you edit the link. The gallery for that share then shows an +**Add photos** button in its header. A share with the option off shows no button, and the upload service refuses it. + +Where uploads go: + +- An album share: into the album. +- A share of selected photos: into the shared link itself, so they show in the same gallery. + +Uploaded files belong to the Immich user who owns the share and count against that user's storage. The owner sees +them in Immich at once and can remove them there. + +A password-protected share asks for its password again on the upload page. The upload service keeps its own unlock, +separate from IPP's, and the password never passes between the two. + +> [!NOTE] +> A share with one photo opens as the image file itself, so there is no header and no button. Set +> [`gallery.singleImage`](/config/gallery#singleimage) to `true` to show a gallery page instead, or give visitors the +> upload page's own link: the share's path on the upload URL, such as `https://upload.example.com/share/`. + +## Set a storage quota + +By default an Immich user has unlimited storage. Set a quota on the user who owns the shares that accept uploads, so +visitors cannot fill the disk: in Immich go to **Administration**, **User Management**, edit the user and set +**Quota Size (GiB)**. Immich refuses uploads past the quota, whatever IPP's own limits allow. + +The upload service also caps each share at 10 GB per hour by default. See +[`upload.byteBudget`](/config/upload-service#bytebudget). + +## Request size limits + +The upload service accepts files up to 500 MB by default ([`upload.maxFileSize`](/config/upload-service#maxfilesize)), +but anything in front of it can impose a lower limit. A file over that limit fails with "Too large for this server". + +- **Caddy** and **Traefik** set no request size limit by default. +- **nginx** allows 1 MB by default. Set `client_max_body_size` to at least `maxFileSize`, and + `proxy_request_buffering off` so nginx streams each file through instead of storing it first. Both are in the + examples above. +- **Cloudflare** refuses requests over 100 MB on the Free and Pro plans, Cloudflare Tunnel included, so larger videos + cannot pass through it. Set `maxFileSize` to `100` so the page tells visitors before the upload starts: + +```json +{ + "ipp": { + "upload": { + "maxFileSize": 100 + } + } +} +``` + +## Tag uploaded photos + +Every uploaded file is stored with `ipp_upload_` at the start of its name +([`upload.filenamePrefix`](/config/upload-service#filenameprefix)). An Immich workflow can match the prefix to tag +uploads, or to copy them into a second album. In Immich, open **Workflows** and create a workflow with: + +1. Trigger: **Asset Upload**. +2. Filter: **Filter by filename**, match type `startsWith`, pattern `ipp_upload_`. +3. Action: **Add Tags** with a tag such as `Sent by visitors`, or **Add to Album(s)**. + +## Get a notification for each upload + +Set [`upload.notifyUrl`](/config/upload-service#notifyurl) to a URL that receives a JSON message for each stored +file. Gotify needs nothing more; ntfy needs the template parameters shown on the reference page. + +## Questions + +### When do uploads appear + +The owner sees them in Immich at once. Other visitors see them in the gallery once three things have happened: + +1. Immich has made the thumbnail. That takes seconds for a photo and longer for a video, and IPP hides a photo until + then. +2. IPP's cache of the share has expired. It is kept for up to 2 minutes. +3. The visitor's browser has fetched the gallery page again. It keeps the page for + [`gallery.cacheTime`](/config/gallery#cachetime), 5 minutes by default. + +So a new photo can take up to about 7 minutes to show for a visitor who already had the gallery open. + +### What happens when a visitor sends a photo the owner already has + +Immich keeps the one copy and adds it to the share. The visitor's list shows the file as a duplicate. + +### Can visitors see who uploaded what, or remove photos + +No. The upload page shows nothing from the share, only the visitor's own uploads in progress, and nothing can be +deleted or edited from it. The owner manages uploads in Immich. + +### Why does the rate limit count all visitors together + +Behind a reverse proxy every visitor reaches the upload service from the proxy's address, so +[`upload.rateLimit`](/config/upload-service#ratelimit) applies to all visitors of a share together. To limit each +visitor separately, set a rate limit in your reverse proxy. + +### How do I turn uploads off + +For one share, turn off **Allow public user to upload** in Immich. Immich refuses new uploads at once, and the button +leaves the gallery on the same cache times as a new photo takes to appear. For all shares, remove `uploadUrl` from +IPP's config and stop the upload container.