diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f9877a..110bfe9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,7 +65,7 @@ app/ thumbhash/, fonts/, images/ style.css, photoswipe-overrides.css tests/ Vitest unit tests for pure functions -docs/ User-facing docs linked from the README +docs/ User docs site (VitePress); docs/README.md explains its structure Dockerfile Multi-stage build, runs as the non-root `node` user docker-compose.yml Reference deployment ``` @@ -102,8 +102,9 @@ Required environment variables (set in `app/.env` or your shell): - `IMMICH_URL` - local URL to your Immich instance. Should not be public. - `PUBLIC_BASE_URL` - optional. Public base URL for IPP without trailing slash. Omit to derive from request hostname. - `IPP_PORT` - optional. Default 3000. +- `IPP_CONFIG` - optional. Path to a config file. All variables: `docs/config/environment-variables.md`. -To exercise the full gallery flow you need a real Immich instance you can hit, with at least one public share created. The README has the user-facing setup steps for spinning that up. +To exercise the full gallery flow you need a real Immich instance you can hit, with at least one public share created. The docs site has the user-facing setup steps (`docs/installation.md`). Configuration overrides go in `app/config.json` or inline via env (see `docs/config/index.md`). Always read config through `getConfigOption('ipp.path.to.key', defaultValue)` rather than reading the JSON directly. @@ -125,7 +126,7 @@ Beyond unit tests, exercise the gallery end-to-end against a real Immich instanc ## Conventions for adding code -**Configuration.** New options go in `app/config.json` under the appropriate `ipp.*` namespace, read via `getConfigOption`, and documented in the relevant table in `README.md`. Prefer a group toggle plus per-field overrides over a single flat boolean when several related toggles cluster, following the `ipp.showMetadata` pattern. Existing keys keep working; if you rename one, add a backward-compat shim with a startup deprecation warning, as was done for the v2.0 gallery key rename. +**Configuration.** New options go in `app/config.json` under the appropriate `ipp.*` namespace, read via `getConfigOption`, and documented on the page for their group under `docs/config/` (see `docs/README.md` for the conventions). Prefer a group toggle plus per-field overrides over a single flat boolean when several related toggles cluster, following the `ipp.showMetadata` pattern. Existing keys keep working; if you rename one, add a backward-compat shim with a startup deprecation warning, as was done for the v2.0 gallery key rename. **Privacy of responses.** Always return 404 for invalid or upstream-failed requests. Use `invalidRequestHandler` rather than crafting ad-hoc error responses. Do not surface Immich status codes or error bodies to the client. @@ -145,6 +146,12 @@ Where to put a new function: ask what category of thing it is, not where it gets **Code style.** ESLint standard config. Run lint locally before opening a PR. +## Documentation + +User-facing documentation is the VitePress site in `docs/`, published at https://docs.ipp.nz. Read `docs/README.md` before adding or moving a page: it sets out the four sidebar groups (Getting started, Configuration, Guides, Troubleshooting - one per kind of content in the Diátaxis sense), where each kind of new material belongs, and the page conventions. Run `npm run build` inside `docs/` before pushing; the build fails on dead internal links. + +The root `README.md` is a front door only: pitch, demo, quick start and links. New content goes on the site. + ## Release process Releases are triggered by pushing a `v*` tag. The `.github/workflows/ci.yaml` workflow builds a multi-arch (`linux/amd64`, `linux/arm64`) image, pushes to both GHCR and Docker Hub, and attaches a build-provenance attestation to each registry. @@ -161,7 +168,7 @@ Do not push tags as part of a PR; releases are cut by the maintainer. For anything non-trivial, open a [Feature Request discussion](https://github.com/alangrainger/immich-public-proxy/discussions/categories/feature-requests) first. The maintainer would rather discuss fit with the read-only/lean philosophy before you spend time on a PR. - Branch from `main`. -- Update the README config tables if you added or changed config keys. +- Update the page under `docs/config/` if you added or changed config keys, following `docs/README.md`. - If your change has a user-visible behavior, include a one-line note in the PR description about how to exercise it. ## What will not be accepted @@ -188,5 +195,6 @@ If you are an AI coding agent working on this repo, the rules above apply to you - **Do not add error handling for cases that cannot happen.** Trust internal invariants. Validate only at the boundary (incoming request, Immich response). - **Default to writing no comments.** Add a comment only when the *why* is non-obvious: a security-relevant invariant, a workaround for a specific upstream bug, or behavior that would surprise a careful reader. Do not narrate the *what*. - **Match the project's existing style.** Server-side Preact SSR, TypeScript ES modules on the client (compiled by `tsc`, no bundler, no framework), plain CSS. Do not introduce new patterns without discussion. +- **Docs changes follow `docs/README.md`.** New material goes in the sidebar group that matches its kind (tutorial, reference, guide, troubleshooting); published page paths stay stable; defaults are checked against `app/config.json`. If something in this guide conflicts with an instruction you have been given, stop and raise the conflict rather than silently working around it. diff --git a/README.md b/README.md index 08ed709..997823d 100644 --- a/README.md +++ b/README.md @@ -20,143 +20,48 @@ serving straight out of my own Immich instance. Setup takes less than a minute, and you never need to touch it again as all of your sharing stays managed within Immich.

- +

-### Table of Contents - -- [About this project](#about-this-project) -- [Installation](#installation) -- [How to use it](#how-to-use-it) -- [How it works](#how-it-works) -- [Configuration](https://docs.ipp.nz/config/) -- [Troubleshooting](#troubleshooting) -- [Feature requests](#feature-requests) - ## About this project -[Immich](https://github.com/immich-app/immich) is a wonderful bit of software, but since it holds all your private photos it's +[Immich](https://github.com/immich-app/immich) is a wonderful bit of software, but since it holds all your private photos it's best to keep it fully locked down. This presents a problem when you want to share a photo or a gallery with someone. **Immich Public Proxy** provides a barrier of security between the public and Immich, and _only_ allows through requests -which you have publicly shared. +which you have publicly shared. It is stateless, needs no API key, and knows nothing about your Immich instance beyond +what you have shared. -It is stateless and does not know anything about your Immich instance. It does not require an API key which reduces the attack -surface even further. The only things that the proxy can access are photos that you have made publicly available in Immich. +Read more in the [Introduction](https://docs.ipp.nz/introduction), including +[why not just expose Immich's `/share/` path](https://docs.ipp.nz/introduction#why-not-expose-immich-directly). -### Features - -- Supports sharing photos and videos. -- Supports password-protected shares. -- If sharing a single image, by default the link will directly open the image file so that you can embed it anywhere you would a normal image. (This is configurable.) -- Gallery styled to match Immich's native look, with light/dark mode following the visitor's system preference. -- Handles very large shares smoothly thanks to virtualized rendering - the browser only keeps tiles near the viewport in the DOM. -- Optional multi-select mode so visitors can pick specific photos and download them together as a zip. -- Optional date-grouped view (off by default), with month headers like "December 2024". -- All usage happens through Immich - you won't need to touch this app after the initial configuration. - -### Why not simply put Immich behind a reverse proxy and only expose the `/share/` path to the public? - -To view a shared album in Immich, you need access to the `/api/` path. If you're sharing a gallery with the public, you need -to make that path public. Any existing or future vulnerability has the potential to compromise your Immich instance. - -For me, the ideal setup is to have Immich secured privately behind mTLS or VPN, and only allow public access to Immich Public Proxy. -Here is an example setup for [securing Immich behind mTLS](./docs/securing-immich-with-mtls.md) using a reverse proxy such as Caddy or Traefik. - -## Installation - -### Install with Docker / Podman +## Quick start 1. Download the [docker-compose.yml](https://github.com/alangrainger/immich-public-proxy/blob/main/docker-compose.yml) file. +2. Set `IMMICH_URL` to the local (not public) URL of your Immich server, and `PUBLIC_BASE_URL` to the public URL of IPP. +3. Run `docker-compose up -d` and check that `https://your-proxy-url.com/share/healthcheck` responds. +4. In Immich's **Server Settings**, set the "External domain" to your IPP URL. Every link Immich generates from now on + points at the proxy. -2. Update the value for `IMMICH_URL` in your docker-compose file to point to your local URL for Immich. This should not be a public URL. +If you use Cloudflare, set your `/share/video/*` path to Bypass Cache or videos may not play. -3. Update or remove the value for `PUBLIC_BASE_URL`. This should be the public base URL for IPP, without a trailing slash (example `https://your-proxy-url.com`). -If you remove this value, it will dynamically generate it based on the request hostname. This can be useful if you are [serving from multiple domains](#serving-from-multiple-domains). +Full instructions, including Kubernetes: **[Installation](https://docs.ipp.nz/installation)**. -4. _Optional_: Add `IPP_PORT` to environment variables in your docker-compose file to change the port from the default of 3000. -This is the _internal_ webserver port inside the container. Most people will not need to do this. Note that you will have to change the `ports` and `healthcheck` sections accordingly. +## Documentation -5. Start the docker container. You can test that it is working by visiting `https://your-proxy-url.com/share/healthcheck`. -Check the container console output for any error messages. +Everything is at **[docs.ipp.nz](https://docs.ipp.nz)**: -```bash -docker-compose up -d -``` - -5. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve Immich Public Proxy: - - - -Now whenever you share an image or gallery through Immich, it will automatically create the correct public path for you. - -🚨 **IMPORTANT**: If you're using Cloudflare, please make sure to set your `/share/video/*` path to Bypass Cache, otherwise you may -run into video playback issues. See [Troubleshooting](#troubleshooting) for more information. - -#### 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 domain. - -See the instructions here: [Running on a single domain](./docs/running-on-single-domain.md). - -#### Redirecting your root domain to a share - -Want `photos.yourdomain.net` to open a specific album instead of the IPP landing page? You can do this with your -reverse proxy - see [Redirecting your root domain to a share](./docs/redirect-root-to-share.md). - -### Install with Kubernetes - -[See the docs here](docs/kubernetes.md). - -## How to use it - -Other than the initial configuration above, everything else is managed through Immich. - -You share your photos/videos as normal through Immich. Because you have set the **External domain** in Immich settings -to be the URL for your proxy app, the links that Immich generates will automaticaly have the correct URL: - - - -## How it works - -When the proxy receives a request, it will come as a link like this: - -``` -https://your-proxy-url.com/share/ffSw63qnIYMtpmg0RNvOui0Dpio7BbxsObjvH8YZaobIjIAzl5n7zTX5d6EDHdOYEvo -``` - -The part after `/share/` is Immich's shared link public ID (called the `key` [in the docs](https://immich.app/docs/api/get-my-shared-link)). -For shared links with a named slug, the link will use the slug instead, e.g. `https://your-proxy-url.com/s/my-album`. - -**Immich Public Proxy** takes that key and makes an API call to your Immich instance over your local network, to ask what -photos or videos are shared in that share URL. - -If it is a valid share URL, the proxy fetches just those assets via local API and returns them to the visitor as an -individual image or gallery. - -If the shared link has expired or any of the assets have been put in the Immich trash, it will not return those. - -All incoming data is validated and sanitised, and anything unexpected is simply dropped with a 404. - -## Configuration - -See **[the configuration docs](https://docs.ipp.nz/config/)** for the full reference. - -## Troubleshooting - -See the [troubleshooting docs](https://docs.ipp.nz/troubleshooting). +- [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), + [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) ## Feature requests You can [add feature requests here](https://github.com/alangrainger/immich-public-proxy/discussions/categories/feature-requests?discussions_q=is%3Aopen+category%3A%22Feature+Requests%22+sort%3Atop), however my goal with this project is to keep it as lean as possible. -Due to the sensitivity of data contained within Immich, this project optimises for auditability: the code -stays small enough that someone with coding experience can review it for security-relevant behavior. - -The most basic rule for this project is that it has **read-only** access to Immich. Things that will not be considered for this project are: - -- Anything that modifies Immich or its files in any way. If it requires an API key or privileged accesss, it won't be considered as a new feature. -- Uploading photos (see above). - -The second rule is that "IPP is stateless and does not know anything about your Immich instance". Anything that would require storing a share key (i.e. the code which gives you access to a share) is unlikely to be added. +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. diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index b7b75be..c9d252e 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,6 +1,5 @@ import { defineConfig } from 'vitepress' -const DEMO_URL = 'https://demo.ipp.nz/s/demo-gallery' const REPO_URL = 'https://github.com/alangrainger/immich-public-proxy' export default defineConfig({ @@ -9,6 +8,8 @@ export default defineConfig({ lang: 'en-NZ', cleanUrls: true, lastUpdated: true, + // README.md is the maintainer's guide to this site, not a page. + srcExclude: ['README.md'], head: [ ['link', { rel: 'icon', href: '/ipp.svg' }] ], @@ -20,39 +21,49 @@ export default defineConfig({ nav: [ { text: 'About', link: '/introduction' }, { text: 'Configuration', link: '/config/' }, - { text: 'Github', link: REPO_URL, target: '_self' } + { text: 'Releases', link: `${REPO_URL}/releases`, target: '_self' } ], + /* One group per kind of content (tutorial, reference, how-to, troubleshooting). + README.md in this folder explains the split; read it before adding a page. + Paths are public URLs: change a label or heading, never a path. */ sidebar: [ { text: 'Getting started', items: [ { text: 'Introduction', link: '/introduction' }, - { text: 'Installation', link: '/installation' }, - { text: 'How to use it', link: '/how-to-use' }, - { text: 'Troubleshooting', link: '/troubleshooting' } + { + text: 'Installation', + link: '/installation', + items: [ + { text: 'Kubernetes', link: '/kubernetes' } + ] + }, + { text: 'Sharing from Immich', link: '/how-to-use' }, + { text: 'Upgrading', link: '/upgrading' } ] }, { - text: 'Config options', + text: 'Configuration', items: [ { text: 'Overview', link: '/config/' }, - { text: 'IPP options', link: '/config/ipp-options' }, + { text: 'Environment variables', link: '/config/environment-variables' }, + { text: 'General options', link: '/config/ipp-options' }, { text: 'Gallery', link: '/config/gallery' }, { text: 'Lightbox', link: '/config/lightbox' }, { text: 'Metadata', link: '/config/metadata' }, { text: 'Error responses', link: '/config/error-responses' }, - { text: 'Upgrading & migration', link: '/config/upgrading' } + { text: 'Legacy config keys', link: '/config/upgrading' } ] }, { - text: 'Deployment', + text: 'Guides', items: [ { 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' }, - { text: 'Install with Kubernetes', link: '/kubernetes' } + { text: 'Securing Immich with mTLS', link: '/securing-immich-with-mtls' } ] - } + }, + { text: 'Troubleshooting', link: '/troubleshooting' } ], socialLinks: [ { icon: 'github', link: REPO_URL } diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts index 530a1d2..5116fbb 100644 --- a/docs/.vitepress/theme/index.ts +++ b/docs/.vitepress/theme/index.ts @@ -1,6 +1,5 @@ import DefaultTheme from 'vitepress/theme' import { h } from 'vue' -import screenshot from '../../screenshot.webp' import './custom.css' const DEMO_URL = 'https://demo.ipp.nz/s/demo-gallery' @@ -44,7 +43,7 @@ export default { }, [ h('img', { - src: screenshot, + src: '/screenshot.webp', alt: 'Immich Public Proxy gallery screenshot', style: 'width: 100%; border-radius: 12px; box-shadow: 0 6px 24px rgba(0, 0, 0, 0.12);' }) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..4e5716d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,78 @@ +# Docs site + +The user documentation at [docs.ipp.nz](https://docs.ipp.nz), built with [VitePress](https://vitepress.dev). This +file is the maintainer's guide to the site and is excluded from the build (`srcExclude` in `.vitepress/config.ts`). +Read it before adding or moving a page. + +## Contents + +- [Working on the site](#working-on-the-site) +- [Structure](#structure) +- [Where new content goes](#where-new-content-goes) +- [Page conventions](#page-conventions) +- [The README](#the-readme) + +## Working on the site + +```bash +cd docs +npm install +npm run dev # live preview +npm run build # fails on dead internal links; run it before pushing +``` + +The sidebar is hand-maintained in `.vitepress/config.ts`, so a new page is invisible until it is added there. +Publishing the built site is a manual step done by the maintainer; a push to `main` does not deploy anything +by itself. +Static files (images, favicon) live in `public/` and are referenced by absolute path, e.g. `/share-link.webp`. + +## Structure + +The site follows the [Diátaxis](https://diataxis.fr) model: every page is one of tutorial, how-to guide, reference or +explanation, and a page never mixes kinds. Each sidebar group holds one kind and is named for the reader's question +rather than the Diátaxis term. + +| Group | Kind | Reader's question | Rules | +|-----------------|-----------|--------------------------------------------|-------| +| Getting started | Tutorial | What is this, and how do I get it running? | Ordered as a path: Introduction, Installation, Sharing from Immich, Upgrading. Numbered steps, one happy path, defaults only. Link to reference pages rather than explaining options inline. | +| Configuration | Reference | What does this key do? | One page per `ipp.*` group, mirroring `app/config.json`. Every key has a `**Type:** … · **Default:** …` line and a short description; each page opens with a worked example. Complete and neutral: no advice, no tutorials. | +| Guides | How-to | How do I achieve this goal? | One goal per page and the title names the goal. Assume IPP is installed. Label every config block with the proxy or platform it is for; Caddy first, then others. | +| Troubleshooting | How-to | Why is this happening? | One page, one `##` per problem. The heading is the symptom as the user sees it (a log line, or what they observe), then the cause, then the fix, then links to the GitHub issues. | + +Explanation (how IPP works, the security model, design principles) lives in **Introduction**. It sits in Getting +started because it is what people read first, not because it is a tutorial. If explanation outgrows one page, add a +"Concepts" group rather than pushing "why" material into a guide or a reference page. + +## Where new content goes + +| You are adding… | Put it in | +|------------------------------------------------|-----------| +| A config key | The page for its group, in `config.json` order, with type and default. If you renamed a key, add a row to Legacy config keys and a shim in `app/src/config/migrations.ts`. | +| An environment variable | `config/environment-variables.md` | +| Something visitors to a share will notice | `how-to-use.md` (Sharing from Immich) | +| A reverse-proxy or hosting recipe | A new page under Guides | +| The fix for a recurring support question | `troubleshooting.md`, symptom first | +| A design decision or a "why" | `introduction.md` | +| Developer or contributor information | `CONTRIBUTING.md` at the repo root, not the site | + +## Page conventions + +- The H1 is the sidebar label. The first paragraph says what the page covers. +- Paths are public URLs, linked from GitHub issues and forums: do not rename or move a published page. Change the + sidebar label and H1 instead. That is why "General options" is served from `/config/ipp-options` and "Sharing from + Immich" from `/how-to-use`. +- Internal links are absolute site paths with optional anchors (`/config/gallery#showtitle`), never relative file + links. Anchors are the heading text lowercased with backticks stripped and spaces as hyphens; keep headings that + are link targets free of other punctuation. +- Config keys are written as `` `gallery.showTitle` `` and linked to their section the first time they appear on a page. +- Callouts use GitHub syntax (`> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`) and are kept for things that bite. +- Code fences are tagged `yaml`, `json` or `bash`. Caddyfiles use a plain fence; there is no highlighter for them. +- Images are `…` with real dimensions so the page does not shift + while loading. +- Types and defaults come from `app/config.json` and the code. Check, don't guess. +- British English, hyphens rather than dashes, and "IPP" after the first "Immich Public Proxy" on a page. + +## The README + +`README.md` at the repo root is the front door, not a second copy of the site: pitch, demo, screenshot, quick start +and links. When something is worth documenting, it goes on the site and the README links to it. diff --git a/docs/config/environment-variables.md b/docs/config/environment-variables.md new file mode 100644 index 0000000..3633864 --- /dev/null +++ b/docs/config/environment-variables.md @@ -0,0 +1,51 @@ +# Environment variables + +Connection and runtime settings are passed as environment variables, typically in the `environment` section of your +`docker-compose.yml`. Only `IMMICH_URL` is required. Everything that controls how shares look and behave is JSON +config instead; see the [Configuration overview](/config/). + +## `IMMICH_URL` + +**Required** + +The URL of your Immich server as reached from inside the IPP container, for example `http://immich_server:2283`. +Use the local address, not your public one: IPP is the only thing that needs to be public. A trailing slash is +ignored. + +From inside a container, `localhost` does not reach Immich. If IPP logs "Unable to reach Immich" at startup, see +[Troubleshooting](/troubleshooting). + +## `PUBLIC_BASE_URL` + +**Optional** · **Default:** derived from each request + +The public base URL of IPP without a trailing slash, for example `https://your-proxy-url.com`. The gallery uses +relative URLs everywhere except the `og:image` tag that messaging apps read for link previews, which must be fully +qualified. When unset, IPP builds it from the incoming request's protocol and `Host` header. + +Set it if link previews show `http://` or a private address. Leave it unset if you serve IPP from several domains, +and make sure your reverse proxy forwards the original `Host` header. + +## `IPP_PORT` + +**Optional** · **Default:** `3000` + +The port the web server listens on inside the container. If you change it, update the `ports` mapping and the +`healthcheck` in your compose file to match. + +## `IPP_CONFIG` + +**Optional** · **Default:** `/app/config.json` + +Path to the JSON config file, either absolute or relative to the working directory. Use it to keep the config +somewhere other than the default path. The usual approach is to mount your file over the default path instead, as +described in the [Configuration overview](/config/#mount-a-file). + +## `CONFIG` + +**Optional** + +The JSON config as an inline string. When set, no config file is read at all. See +[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. diff --git a/docs/config/gallery.md b/docs/config/gallery.md index d01adcc..d761262 100644 --- a/docs/config/gallery.md +++ b/docs/config/gallery.md @@ -85,6 +85,6 @@ Show the bulk-zip download UI - the "download all" button in the header and the ## `cacheTime` -**Type:** `int` +**Type:** `int` · **Default:** `300` How long (in seconds) browsers and any CDN may cache the gallery **page** before revalidating. Set this longer to reduce load on your server, but be aware that if you add new photos to a gallery they won't show up until the cache times out or you manually clear any downstream caches. diff --git a/docs/config/index.md b/docs/config/index.md index ee860db..120a448 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -3,21 +3,22 @@ > [!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. -All options live under `ipp.*`, grouped into: +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: -- [IPP options](/config/ipp-options) - top-level proxy behaviour. +- [General options](/config/ipp-options) - downloads, zoom quality, slug links, 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. -- [Upgrading & migration](/config/upgrading) - renamed keys and compatibility shims. +- [Legacy config keys](/config/upgrading) - renamed keys and compatibility shims. ## How to provide a config override > [!NOTE] -> You only need to include the keys you're changing. Anything you omit keeps its default. The defaults in IPP are always the most privacy-respecting option. +> You only need to include the keys you're changing. Anything you omit keeps its default, and the defaults are always the most privacy-respecting option. In particular the metadata groups are per-field opt-in: nothing is exposed until you set its flag to `true`, including fields IPP adds in future versions. -There are two ways to supply custom config. +There are two ways to supply custom config. If both are present, `CONFIG` wins and the file is not read. ### Mount a file @@ -45,9 +46,3 @@ For one-off or single-key overrides, pass the configuration inline from your `do } } ``` - -## How options are organised - -All options live under `ipp.*`. The metadata groups (`ipp.showMetadata.exif`, `ipp.showMetadata.location`) are per-field opt-in: every field is off until you explicitly set its flag to `true`. Nothing is automatically exposed - including fields IPP adds in future versions. - -You only need to include the keys you're changing. Anything you omit keeps its default. diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index 980d6e0..af984b3 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -1,6 +1,6 @@ -# IPP options +# General options -Top-level options under `ipp.*`. +Top-level options under `ipp.*` that don't belong to the [Gallery](/config/gallery), [Lightbox](/config/lightbox) or [Metadata](/config/metadata) groups. ## Example @@ -19,7 +19,18 @@ Serve full-resolution images both when zooming in the lightbox and when download **Type:** `object` -Change the headers sent with your web responses. By default there is `cache-control` and CORS added. +Change the headers sent with your web responses. The default is a 30-day `Cache-Control` and a permissive CORS header: + +```json +{ + "ipp": { + "responseHeaders": { + "Cache-Control": "public, max-age=2592000", + "Access-Control-Allow-Origin": "*" + } + } +} +``` ## `maxDownloadQuality` @@ -77,13 +88,13 @@ The bulk-zip and per-asset buttons can be toggled independently once downloads a ## `allowSlugLinks` -**Type:** `bool` +**Type:** `bool` · **Default:** `true` -Enable/disable the custom URL links. +Serve shared links that have a custom URL in Immich at `/s/` as well as `/share/`. Set to `false` to return a 404 for slug links, so that only the key form works. ## `showHomePage` -**Type:** `bool` +**Type:** `bool` · **Default:** `true` Set to `false` to remove the IPP shield page at `/` and at `/share`. diff --git a/docs/config/metadata.md b/docs/config/metadata.md index 4bdda25..d262e90 100644 --- a/docs/config/metadata.md +++ b/docs/config/metadata.md @@ -83,29 +83,3 @@ Under `ipp.showMetadata.location`. Every flag defaults to `false`, except `webLi | `country` | `bool` | Show country. | | `gps` | `bool` | Show GPS coordinates. | | `webLink` | `bool` | Show an "Open in OpenStreetMap" link below the coordinates. The link is rendered with `rel="noreferrer"` so the share URL is not leaked to the map provider when a viewer clicks it. Has no effect unless `gps` is also true. Default `true`. | - -## Example - -Show the description in the sidebar only (not as a lightbox caption), expose camera EXIF, and reveal place names but not the GPS coordinates: - -```json -{ - "ipp": { - "showMetadata": { - "description": { "caption": false, "sidebar": true }, - "exif": { - "dateTimeOriginal": true, - "timeZone": true, - "make": true, - "model": true, - "lensModel": true, - "exposureTime": true, - "iso": true, - "fNumber": true, - "focalLength": true - }, - "location": { "city": true, "state": true, "country": true } - } - } -} -``` diff --git a/docs/config/upgrading.md b/docs/config/upgrading.md index 83979b4..e67e13b 100644 --- a/docs/config/upgrading.md +++ b/docs/config/upgrading.md @@ -1,6 +1,6 @@ -# Upgrading & migration +# Legacy config keys -A few config keys have been renamed across versions. Existing configs continue to work via backward-compatibility shims and a startup deprecation notice. +A few config keys have been renamed or reshaped across versions. Old configs keep working through backward-compatibility shims, with a deprecation notice logged at startup; update to the current names to silence it. For how to update IPP itself, see [Upgrading](/upgrading). ## Gallery keys moved under `ipp.gallery.*` (v2.0) diff --git a/docs/external-link.png b/docs/external-link.png deleted file mode 100644 index 1e00739..0000000 Binary files a/docs/external-link.png and /dev/null differ diff --git a/docs/how-to-use.md b/docs/how-to-use.md index 904a2e1..4f1d26a 100644 --- a/docs/how-to-use.md +++ b/docs/how-to-use.md @@ -1,8 +1,45 @@ -# How to use it +# Sharing from Immich -Other than the initial configuration during [installation](/installation), everything else is managed through Immich. +Other than the initial configuration during [installation](/installation), everything is managed through Immich. +IPP has no admin interface of its own. -You share your photos/videos as normal through Immich. Because you have set the **External domain** in Immich settings -to be the URL for your proxy app, the links that Immich generates will automatically have the correct URL: +Share your photos, videos and albums as normal through Immich. Because you set the **External domain** in Immich's +settings to the URL of IPP, the links Immich generates already point at the proxy: Sharing a link from Immich + +## Share links + +A standard link looks like `https://your-proxy-url.com/share/`, where the key is the shared link's public ID +in Immich. If you give the shared link a custom URL in Immich, IPP serves it at `https://your-proxy-url.com/s/` +instead. Slug links can be turned off with [`allowSlugLinks`](/config/ipp-options#allowsluglinks). + +The settings on the shared link in Immich are respected: + +- **Password.** Visitors must enter the password before IPP serves anything from the share. It is remembered in an + encrypted cookie for an hour, after which they are asked again. +- **Expiry.** An expired link returns a 404, the same as an unknown one. The expiry date can be shown on the gallery + with [`gallery.showExpiryDate`](/config/gallery#showexpirydate). +- **Allow downloads.** Decides whether Immich will serve the original files. See + [`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). + +## What visitors see + +- A share containing a single image opens the image file directly, so you can embed the link anywhere you would a + normal image. Set [`gallery.singleImage`](/config/gallery#singleimage) to show a gallery page instead. A single video + opens a gallery page by default ([`gallery.singleVideo`](/config/gallery#singlevideo)). +- Everything else opens as a gallery styled to match Immich, in light or dark mode following the visitor's system + preference, with a lightbox for viewing each photo or video. +- Very large shares stay smooth: the gallery is virtualised, so the browser only keeps the tiles near the viewport in + the page. +- When downloads are allowed, visitors can download a single item, select several to download together as a zip, or + download the whole share. +- 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. + +Try it on the [live demo](https://demo.ipp.nz/s/demo-gallery). + +Next: [Upgrading](/upgrading), or head to [Configuration](/config/) to tune the gallery. diff --git a/docs/index.md b/docs/index.md index beef67e..462dc5b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,8 +11,8 @@ hero: link: https://demo.ipp.nz/s/demo-gallery target: _self - theme: alt - text: Getting started - link: /introduction + text: Get started + link: /installation - theme: alt text: Configuration link: /config/ diff --git a/docs/installation.md b/docs/installation.md index 034e9ab..fb2d98a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -34,11 +34,24 @@ you. > If you're using Cloudflare, please make sure to set your `/share/video/*` path to Bypass Cache, otherwise you may > run into video playback issues. See [Troubleshooting](/troubleshooting) for more information. +Those two variables are all most people need. The port and the config file location are covered under +[Environment variables](/config/environment-variables), and everything about how galleries look and behave under +[Configuration](/config/). + +### Docker images + +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 +at the newest release. + ### Running alongside Immich on a single domain -Because all IPP paths are under `/share/...`, you can run Immich Public Proxy and Immich on the same domain. See -[Running on a single domain](/running-on-single-domain). +Because all IPP paths are under `/share/...` and `/s/...`, you can run Immich Public Proxy and Immich on the same +domain. See [Running on a single domain](/running-on-single-domain). ## Install with Kubernetes See the [Kubernetes install docs](/kubernetes). + +Next: [Sharing from Immich](/how-to-use). diff --git a/docs/introduction.md b/docs/introduction.md index 62013e7..03223f0 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -4,7 +4,7 @@ photos it's best to keep it fully locked down. This presents a problem when you want to share a photo or a gallery with someone. -**Immich Public Proxy** provides a barrier of security between the public and Immich, and _only_ allows through +**Immich Public Proxy** (IPP) provides a barrier of security between the public and Immich, and _only_ allows through requests which you have publicly shared. It is stateless and does not know anything about your Immich instance. It does not require an API key which reduces @@ -20,6 +20,7 @@ https://your-proxy-url.com/share/ffSw63qnIYMtpmg0RNvOui0Dpio7BbxsObjvH8YZaobIjIA ``` The part after `/share/` is Immich's shared link public ID (called the `key` [in the docs](https://api.immich.app/endpoints/shared-links/getMySharedLink)). +For shared links given a custom URL in Immich, the link uses that slug instead, e.g. `https://your-proxy-url.com/s/my-album`. **Immich Public Proxy** takes that key and makes an API call to your Immich instance over your local network, to ask what photos or videos are shared in that share URL. @@ -31,4 +32,29 @@ If the shared link has expired or any of the assets have been put in the Immich All incoming data is validated and sanitised, and anything unexpected is simply dropped with a 404. +## Why not expose Immich directly? + +A common alternative is to put Immich behind a reverse proxy and only expose its `/share/` path to the public. The +catch is that viewing a shared album in Immich also needs access to the `/api/` path, so that has to be public too, +and any existing or future vulnerability in it has the potential to compromise your whole Immich instance. + +IPP removes that exposure: Immich stays private, and the only thing on the internet is a small read-only proxy that +can't do anything except serve what you have already shared. The ideal setup is Immich secured behind mTLS or a VPN, +with public access only to IPP. See [Securing Immich with mTLS](/securing-immich-with-mtls) for an example. + +## Design principles + +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. +- **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 + with coding experience to review its security-relevant behaviour. + +Feature requests are welcome in [GitHub Discussions](https://github.com/alangrainger/immich-public-proxy/discussions/categories/feature-requests), +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. + Ready to set it up? Head to [Installation](/installation). diff --git a/docs/kubernetes.md b/docs/kubernetes.md index c50deb5..a2915b2 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -1,9 +1,10 @@ # Install with Kubernetes -See the [official Immich docs](https://immich.app/docs/install/kubernetes/) for additional information. This deployment uses the common chart Immich depends on ([bjw-s common library chart](https://github.com/bjw-s-labs/helm-charts/tree/common-5.0.1/charts/library/common)) to extend the deployment as described in the [Immich docs](https://github.com/immich-app/immich-charts/blob/main/README.md) +See the [official Immich docs](https://immich.app/docs/install/kubernetes/) for additional information. This deployment uses the common chart Immich depends on ([bjw-s common library chart](https://github.com/bjw-s-labs/helm-charts/tree/common-5.0.1/charts/library/common)) to extend the deployment as described in the [Immich docs](https://github.com/immich-app/immich-charts/blob/main/README.md). -1. Simply modify the values of your immich deployment in the server section. The next example shows using the new Gateway API HTTPRoute, below you can also find the old Ingress version. This uses -``` +Modify the values of your Immich deployment in the `server` section. The first example uses the newer Gateway API `HTTPRoute`; the Ingress version follows it. + +```yaml server: enabled: true @@ -39,10 +40,10 @@ server: main: image: repository: alangrainger/immich-public-proxy - tag: 3.2.0 + tag: 3.3.0 # pin to the current release: https://github.com/alangrainger/immich-public-proxy/releases pullPolicy: IfNotPresent env: - IMMICH_URL: https://your-immich-url.com // You could also reference the service here + IMMICH_URL: http://immich-server-main:2283 # the in-cluster Immich service, not your public URL PUBLIC_BASE_URL: https://your-proxy-url.com service: @@ -53,15 +54,18 @@ server: http: port: 3000 - serviceMonitor: // We modify the ServiceMonitor here, as the bjw-s common chart can get confused with more than 1 service (main and immich-public-proxy) + # The bjw-s common chart can get confused with more than one service (main and + # immich-public-proxy), so the ServiceMonitor is pinned to the main service here. + serviceMonitor: main: - enabled: false // Set to true if you need metrics + enabled: false # set to true if you need metrics service: identifier: main ``` -Or with Ingress -``` +Or with Ingress: + +```yaml server: enabled: true ingress: @@ -84,7 +88,4 @@ server: pathType: Prefix service: identifier: immich-public-proxy -... ``` - - diff --git a/docs/cloudflare-video-cache.webp b/docs/public/cloudflare-video-cache.webp similarity index 100% rename from docs/cloudflare-video-cache.webp rename to docs/public/cloudflare-video-cache.webp diff --git a/docs/screenshot.webp b/docs/public/screenshot.webp similarity index 100% rename from docs/screenshot.webp rename to docs/public/screenshot.webp diff --git a/docs/server-settings.png b/docs/public/server-settings.png similarity index 100% rename from docs/server-settings.png rename to docs/public/server-settings.png diff --git a/docs/share-link.webp b/docs/public/share-link.webp similarity index 100% rename from docs/share-link.webp rename to docs/public/share-link.webp diff --git a/docs/securing-immich-with-mtls.md b/docs/securing-immich-with-mtls.md index 7ab8e77..2aaf63d 100644 --- a/docs/securing-immich-with-mtls.md +++ b/docs/securing-immich-with-mtls.md @@ -2,9 +2,11 @@ Immich supports using a custom client certificate on both web and mobile apps, so it's one of the easiest and safest ways to limit access to only clients of your choice. +This guide is about Immich rather than IPP: it locks Immich itself down so that only IPP is reachable from the internet, the setup described in [Why not expose Immich directly?](/introduction#why-not-expose-immich-directly). The reverse-proxy examples below apply mTLS to Immich only; IPP stays open to the public. + ## Authenticating with mutual TLS -The process of generating the certificates is the same regardless of which reverse proxy you use. Just make sure to place the folder "certs/" under a volume that is mounted to your reverse proxy container. +The process of generating the certificates is the same regardless of which reverse proxy you use. Place the resulting `certs/` folder inside a volume that is mounted into your reverse proxy container: `./data/certs` for the Caddy example below, `./config/certs` for Traefik. ### Generate your client certificate @@ -31,7 +33,7 @@ echo echo "Please enter a STRONG password. Many clients *require* a password for you to be able to import the certificate, and you want to protect it." echo -# Convert the cerificate to PKCS12 format (for import into browser) +# Convert the certificate to PKCS12 format (for import into browser) openssl pkcs12 -export -out certs/client.pfx -inkey certs/client.key -in certs/client.crt # Clean up @@ -59,12 +61,12 @@ services: ``` ### Configure Caddyfile -```Caddyfile +``` https://immich.mydomain.com { tls { client_auth { mode require_and_verify - trusted_ca_cert_file /data/client_certs/client.crt + trusted_ca_cert_file /data/certs/client-ca.crt } } reverse_proxy internal_server.lan:2283 @@ -89,7 +91,7 @@ services: - ./config:/etc/traefik ``` -### Configure Traefik dynamic file: +### Configure Traefik dynamic file ```yaml http: services: @@ -119,6 +121,6 @@ tls: - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 clientAuth: caFiles: - - /etc/traefik/certs/client.crt + - /etc/traefik/certs/client-ca.crt clientAuthType: RequireAndVerifyClientCert ``` diff --git a/docs/shield.png b/docs/shield.png deleted file mode 100644 index 5954350..0000000 Binary files a/docs/shield.png and /dev/null differ diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 0000000..c7d22ec --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,29 @@ +# Upgrading + +## Updating IPP + +IPP keeps no state, so updating is a matter of pulling the new image and recreating the container: + +```bash +docker-compose pull +docker-compose up -d +``` + +If you pin a version tag rather than `latest`, bump it in your `docker-compose.yml` first (see +[Docker images](/installation#docker-images) for the tag scheme). + +Check the [release notes](https://github.com/alangrainger/immich-public-proxy/releases) before moving to a new major +version. Breaking changes and renamed config keys land in major versions and are listed there. + +## Immich version + +IPP requires **Immich 2.0.0 or newer** and checks the server version at startup. Against an older Immich it logs a +fatal error and exits; if it can't determine the version at all (Immich unreachable), it logs a warning and carries on. + +When you upgrade Immich, check the IPP release notes for a matching release, as changes to Immich's API are picked up +there. + +## Config keys + +Renamed or reshaped config keys keep working through backward-compatibility shims, with a deprecation notice logged +at startup. [Legacy config keys](/config/upgrading) maps each old form to its current name.