Update docs
@@ -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,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);'
|
||||
})
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
|
||||
@@ -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 }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 974 B |
@@ -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.
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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 |
@@ -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
|
||||
```
|
||||
|
||||
|
Before Width: | Height: | Size: 16 KiB |
@@ -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.
|
||||