From daa099aca1527296610a58af740f3cdf74714ba5 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Wed, 7 Oct 2026 14:53:14 +1300 Subject: [PATCH] Update docs --- docker-compose.yml | 1 - docs/config/ipp-options.md | 4 +- docs/config/upload-service.md | 15 ++---- docs/upgrading.md | 1 - docs/visitor-uploads.md | 88 ++++++++++++++++----------------- upload-app/src/config.ts | 13 ----- upload-app/src/index.ts | 27 ++++++---- upload-app/tests/config.test.ts | 19 +------ 8 files changed, 69 insertions(+), 99 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 94d62cc..379fd55 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -24,7 +24,6 @@ services: # - "3001:3000" # environment: # IMMICH_URL: http://your-internal-immich-server:2283 - # PUBLIC_BASE_URL: https://upload.example.com # GALLERY_URL: https://your-proxy-url.com # healthcheck: # test: curl -sf -m 4 http://localhost:3000/healthcheck -o /dev/null || exit 1 diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index 376c016..574fd60 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -108,9 +108,9 @@ The bulk-zip and per-asset buttons can be toggled independently once downloads a **Type:** `string` ยท **Default:** `""` -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 public URL of the optional upload service (the `immich-public-proxy-upload` container), for example `https://photos.example.com/upload`. 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). +The value is wherever your reverse proxy serves the upload service, with the path if it has one. To set up the service, see [Let visitors send photos back](/visitor-uploads). ## `allowSlugLinks` diff --git a/docs/config/upload-service.md b/docs/config/upload-service.md index 1282f57..ee4a15d 100644 --- a/docs/config/upload-service.md +++ b/docs/config/upload-service.md @@ -26,16 +26,7 @@ Accept files up to 2 GB, and send a notification to a Gotify server for each sto ## 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. +[Environment variables](/config/environment-variables). `IMMICH_URL` is required. The service has one more: ### `GALLERY_URL` @@ -44,6 +35,10 @@ either way. 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. +The service has no setting for its own public URL. It serves its pages both under `/upload` and at the root, so the +reverse proxy decides where it lives: a path on the IPP hostname (`photos.example.com/upload`) or a hostname of its +own (`upload.example.com`). See [Route it through your reverse proxy](/visitor-uploads#route-it-through-your-reverse-proxy). + ## Options ### `maxFileSize` diff --git a/docs/upgrading.md b/docs/upgrading.md index e44ba40..585dd7e 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -60,7 +60,6 @@ services: - "3001:3000" environment: IMMICH_URL: http://your-internal-immich-server:2283 - PUBLIC_BASE_URL: https://upload.example.com GALLERY_URL: https://your-proxy-url.com healthcheck: test: curl -sf -m 4 http://localhost:3000/healthcheck -o /dev/null || exit 1 diff --git a/docs/visitor-uploads.md b/docs/visitor-uploads.md index 507bc4b..052a1c6 100644 --- a/docs/visitor-uploads.md +++ b/docs/visitor-uploads.md @@ -49,9 +49,9 @@ Other visitors see the new photos in the gallery within a few minutes. See ## 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. +- A public route to the upload service: a path on the IPP hostname, such as `photos.example.com/upload`, or its own + hostname, such as `upload.example.com`. 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 @@ -70,7 +70,6 @@ services: - "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 -sf -m 4 http://localhost:3000/healthcheck -o /dev/null || exit 1 @@ -79,50 +78,23 @@ services: ``` - `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. +- `GALLERY_URL` is the public URL of IPP, the same value as IPP's `PUBLIC_BASE_URL`. It gives the upload page a back + button to the gallery. + +The service has no setting for its own public URL. Your reverse proxy decides that in the next step. 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; - } -} -``` +The upload service serves its pages both under `/upload` and at the root, so it fits either of these shapes with no +URL setting. 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. ### 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. +One domain, no extra certificate. Forward `/upload/*` 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): @@ -156,18 +128,46 @@ server { } ``` -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 +### 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; + } +} +``` + +Check the route by opening `/healthcheck` on the upload URL: `https://photos.example.com/upload/healthcheck` or +`https://upload.example.com/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`: +Set [`uploadUrl`](/config/ipp-options#uploadurl) in IPP's config to the public URL you routed in the previous step: ```json { "ipp": { - "uploadUrl": "https://upload.example.com" + "uploadUrl": "https://photos.example.com/upload" } } ``` diff --git a/upload-app/src/config.ts b/upload-app/src/config.ts index 276720c..8e4bcc3 100644 --- a/upload-app/src/config.ts +++ b/upload-app/src/config.ts @@ -2,19 +2,6 @@ import { getConfigOption, getNumericConfigOption } from '@ipp/core' const MB = 1024 * 1024 -/** - * Path the share routes are mounted under, from `PUBLIC_BASE_URL`: `''` for - * an own-hostname deployment, `/upload` for `https://photos.example.com/upload`. - */ -export function basePathFrom (publicBaseUrl: string | undefined): string { - if (!publicBaseUrl) return '' - try { - return new URL(publicBaseUrl).pathname.replace(/\/+$/, '') - } catch { - return '' - } -} - /** IPP's public URL from `GALLERY_URL`, without a trailing slash, or undefined when unset. */ export function galleryUrl (): string | undefined { return (process.env.GALLERY_URL || '').replace(/\/+$/, '') || undefined diff --git a/upload-app/src/index.ts b/upload-app/src/index.ts index aa22137..f5f2371 100644 --- a/upload-app/src/index.ts +++ b/upload-app/src/index.ts @@ -28,7 +28,7 @@ import { title, unlockHandler } from '@ipp/core' -import { basePathFrom, galleryUrl, maxFileSize } from './config' +import { galleryUrl, maxFileSize } from './config' import { uploadAllowed } from './gate' import { createUploadReceiver } from './receive' import { getShare } from './share' @@ -40,7 +40,6 @@ import { UploadPage } from './view/upload' // the image. loadConfig({ defaultPath: resolve(__dirname, '../config.json') }) -const basePath = basePathFrom(process.env.PUBLIC_BASE_URL) const receiveUpload = createUploadReceiver() const inProduction = process.env.NODE_ENV === 'production' @@ -62,7 +61,10 @@ router.use((_req, res, next) => { addNoStoreHeaders(res) next() }) -router.use(sessionMiddleware({ name: 'upload-session', path: basePath || '/' })) +router.use(sessionMiddleware({ name: 'upload-session' })) + +// Before the share routes, which would otherwise read "healthcheck" as a key +router.get(['/healthcheck', '/share/healthcheck'], asyncHandler(healthcheck)) type ShareResolution = | { ok: true, link: SharedLink, keyType: KeyType } @@ -87,7 +89,7 @@ router.get('/:shareType(share|s)/:key', decodeCookie, asyncHandler(async (req, r const resolved = await resolveShare(req) if (!resolved.ok && resolved.passwordRequired) { if (req.password) invalidPasswordResponse(req, res, key) - res.send(renderPage(h(Password, { shareKey: key, notifyInvalidPassword: !!req.password, basePath }))) + res.send(renderPage(h(Password, { shareKey: key, notifyInvalidPassword: !!req.password, basePath: req.baseUrl }))) return } if (!resolved.ok || !uploadAllowed(resolved.link, resolved.keyType)) { @@ -97,11 +99,11 @@ router.get('/:shareType(share|s)/:key', decodeCookie, asyncHandler(async (req, r const gallery = galleryUrl() res.send(renderPage(h(UploadPage, { config: { - uploadUrl: `${basePath}/${req.params.shareType}/${encodeURIComponent(key)}/upload`, + uploadUrl: `${req.baseUrl}/${req.params.shareType}/${encodeURIComponent(key)}/upload`, maxFileSize: maxFileSize(), title: title(resolved.link) }, - basePath, + basePath: req.baseUrl, galleryLink: gallery && `${gallery}/${req.params.shareType}/${encodeURIComponent(key)}` }))) })) @@ -124,9 +126,14 @@ router.post('/:shareType(share|s)/:key/upload', decodeCookie, asyncHandler(async await receiveUpload(req, res, resolved.link, resolved.keyType) })) -router.get(['/healthcheck', '/share/healthcheck'], asyncHandler(healthcheck)) - -app.use(basePath || '/', router) +/* + * The same routes under `/upload` and at the root, so either reverse proxy + * shape works with no URL configuration: a hostname of its own forwards + * `/share/`, a path on the IPP hostname forwards `/upload/share/`. + * Handlers read the prefix they were reached by from `req.baseUrl`. + */ +app.use('/upload', router) +app.use('/', router) /* * Everything else, including `/`, gets the 404 policy @@ -154,7 +161,7 @@ process.on('SIGTERM', () => { const port = Number(process.env.IPP_PORT) || 3000 const server = app.listen(port, () => { - console.log(dayjs().format() + ' Upload service started on port ' + port + (basePath ? ' under ' + basePath : '')) + console.log(dayjs().format() + ' Upload service started on port ' + port) enforceMinimumImmichVersion().catch(() => {}) }) // A large video on a phone uplink outlasts any whole-request limit; the body has an idle timeout instead diff --git a/upload-app/tests/config.test.ts b/upload-app/tests/config.test.ts index 69fb605..f500524 100644 --- a/upload-app/tests/config.test.ts +++ b/upload-app/tests/config.test.ts @@ -1,28 +1,11 @@ import { describe, it, expect, afterEach } from 'vitest' -import { basePathFrom, byteBudget, filenamePrefix, maxFileSize, notifyConfig } from '../src/config' +import { byteBudget, filenamePrefix, maxFileSize, notifyConfig } from '../src/config' import { resetConfig, setConfig } from './helpers' afterEach(resetConfig) const MB = 1024 * 1024 -describe('basePathFrom', () => { - it('is empty for an own-hostname deployment', () => { - expect(basePathFrom('https://upload.example.com')).toBe('') - expect(basePathFrom('https://upload.example.com/')).toBe('') - expect(basePathFrom(undefined)).toBe('') - }) - - it('is the URL path for a path-prefix deployment, without a trailing slash', () => { - expect(basePathFrom('https://photos.example.com/upload')).toBe('/upload') - expect(basePathFrom('https://photos.example.com/a/b/')).toBe('/a/b') - }) - - it('is empty for a value that is not a URL', () => { - expect(basePathFrom('not a url')).toBe('') - }) -}) - describe('upload options', () => { it('has the documented defaults', () => { expect(maxFileSize()).toBe(500 * MB)