Update docs

This commit is contained in:
Alan Grainger
2026-09-04 12:55:08 +12:00
parent 18284ef5c5
commit ff45919107
24 changed files with 349 additions and 209 deletions
+23 -12
View File
@@ -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 }
+1 -2
View File
@@ -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);'
})
+78
View File
@@ -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 `<img src="/name.webp" width="…" height="…" alt="…">` 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.
+51
View File
@@ -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.
+1 -1
View File
@@ -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.
+6 -11
View File
@@ -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.
+17 -6
View File
@@ -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/<slug>` as well as `/share/<key>`. 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`.
-26
View File
@@ -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 }
}
}
}
```
+2 -2
View File
@@ -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)
Binary file not shown.

Before

Width:  |  Height:  |  Size: 974 B

+41 -4
View File
@@ -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:
<img src="/share-link.webp" width="751" height="524" alt="Sharing a link from Immich">
## Share links
A standard link looks like `https://your-proxy-url.com/share/<key>`, 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/<slug>`
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.
+2 -2
View File
@@ -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/
+15 -2
View File
@@ -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).
+27 -1
View File
@@ -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).
+13 -12
View File
@@ -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
...
```

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 32 KiB

Before

Width:  |  Height:  |  Size: 95 KiB

After

Width:  |  Height:  |  Size: 95 KiB

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

Before

Width:  |  Height:  |  Size: 33 KiB

After

Width:  |  Height:  |  Size: 33 KiB

+8 -6
View File
@@ -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
```
BIN
View File
Binary file not shown.

Before

Width:  |  Height:  |  Size: 16 KiB

+29
View File
@@ -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.