Update docs

This commit is contained in:
Alan Grainger
2026-10-06 15:17:11 +13:00
parent 7a20c72f77
commit 20c4238b6e
12 changed files with 478 additions and 9 deletions
+2
View File
@@ -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' }
+2
View File
@@ -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).
+2 -1
View File
@@ -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
+2
View File
@@ -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`
+169
View File
@@ -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/<slug>`
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. |
+4
View File
@@ -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).
+4 -1
View File
@@ -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
+14 -1
View File
@@ -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).
+7
View File
@@ -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
+255
View File
@@ -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/<key>`.
## 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.