Update docs

This commit is contained in:
Alan Grainger
2026-10-09 10:54:12 +13:00
parent 7dad93faaf
commit ae5011f996
12 changed files with 24 additions and 23 deletions
+1 -1
View File
@@ -39,7 +39,7 @@ Read more in the [Introduction](https://docs.ipp.nz/introduction), including
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.
3. Run `docker-compose up -d` and check that `https://photos.example.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.
+3 -2
View File
@@ -27,7 +27,8 @@ and rendered by the theme, so visitors' browsers never call GitHub. A local buil
and omits the pill; nothing is wrong. The deploy workflow also rebuilds weekly so the number stays current.
The sidebar is hand-maintained in `.vitepress/config.ts`, so a new page is invisible until it is added there.
Static files (images, favicon) live in `public/` and are referenced by absolute path, e.g. `/share-link.webp`.
Static files (images, favicon) live in `public/` and are referenced by relative path, e.g. `./public/share-link.webp`,
which renders on GitHub as well; VitePress rewrites it to a hashed asset at build time.
`public/CNAME` holds the custom domain; it is copied to the root of the build and must stay there.
Publishing is automatic. Any push to `main` that touches `docs/` runs the `docs.yaml` workflow, which builds the
@@ -78,7 +79,7 @@ started because it is what people read first, not because it is a tutorial. If e
- 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
- Images are `<img src="./public/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 `upload-app/config.json`. The build checks them; see
[Config reference pages](#config-reference-pages).
+1 -1
View File
@@ -19,7 +19,7 @@ From inside a container, `localhost` does not reach Immich. If IPP logs "Unable
**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
The public base URL of IPP without a trailing slash, for example `https://photos.example.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.
+1 -1
View File
@@ -49,7 +49,7 @@ For one or two keys, pass the JSON in the `CONFIG` environment variable instead
```yaml
environment:
PUBLIC_BASE_URL: https://your-proxy-url.com
PUBLIC_BASE_URL: https://photos.example.com
IMMICH_URL: http://your-internal-immich-server:2283
CONFIG: |
{
+3 -3
View File
@@ -6,12 +6,12 @@ IPP has no admin interface of its own.
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">
<img src="./public/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>`
A standard link looks like `https://photos.example.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://photos.example.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:
+3 -3
View File
@@ -12,7 +12,7 @@
not be a public URL.** Most likely this will be a local IP and port; whatever your Immich container runs on.
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
slash (example `https://photos.example.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](/running-on-single-domain).
4. Start the docker container. Check the container console output for any error messages.
@@ -23,12 +23,12 @@ docker-compose up -d
5. Point your reverse proxy at the container on port 3000, so IPP is served over HTTPS at your `PUBLIC_BASE_URL`.
See [Put IPP behind a reverse proxy](/reverse-proxy) for Caddy, nginx and Traefik examples. You can test that it
is working by visiting `https://your-proxy-url.com/share/healthcheck`.
is working by visiting `https://photos.example.com/share/healthcheck`.
6. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve
Immich Public Proxy:
<img src="/server-settings.png" width="400" height="182" alt="Immich server settings - external domain">
<img src="./public/server-settings.png" width="445" height="181" alt="Immich server settings - external domain">
Now whenever you share an image or gallery through Immich, it will automatically create the correct public path for
you.
+2 -2
View File
@@ -16,11 +16,11 @@ available in Immich.
When the proxy receives a request, it will come as a link like this:
```
https://your-proxy-url.com/share/ffSw63qnIYMtpmg0RNvOui0Dpio7BbxsObjvH8YZaobIjIAzl5n7zTX5d6EDHdOYEvo
https://photos.example.com/share/ffSw63qnIYMtpmg0RNvOui0Dpio7BbxsObjvH8YZaobIjIAzl5n7zTX5d6EDHdOYEvo
```
The part after `/share/` is the shared link's key in Immich. A shared link with a custom URL in Immich uses that
instead, e.g. `https://your-proxy-url.com/s/my-album`.
instead, e.g. `https://photos.example.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.
+5 -5
View File
@@ -16,7 +16,7 @@ server:
- name: gateway
namespace: kube-system
hostnames:
- your-immich-url.com
- immich.example.com
rules:
- backendRefs:
- name: immich-server-main
@@ -28,7 +28,7 @@ server:
- name: gateway
namespace: kube-system
hostnames:
- your-proxy-url.com
- photos.example.com
rules:
- backendRefs:
- name: immich-server-immich-public-proxy
@@ -44,7 +44,7 @@ server:
pullPolicy: IfNotPresent
env:
IMMICH_URL: http://immich-server-main:2283 # the in-cluster Immich service, not your public URL
PUBLIC_BASE_URL: https://your-proxy-url.com
PUBLIC_BASE_URL: https://photos.example.com
# Optional lockdown: IPP writes nothing to disk and needs no extra privileges
securityContext:
readOnlyRootFilesystem: true
@@ -80,7 +80,7 @@ server:
enabled: true
hosts:
- host: your-immich-url.com
- host: immich.example.com
paths:
- path: /
pathType: Prefix
@@ -89,7 +89,7 @@ server:
immich-public-proxy:
enabled: true
hosts:
- host: your-proxy-url.com
- host: photos.example.com
paths:
- path: /
pathType: Prefix
Binary file not shown.

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 43 KiB

+1 -1
View File
@@ -10,7 +10,7 @@ An example Caddyfile. The `basic_auth` block protects Immich itself; see the
[Caddy docs](https://caddyserver.com/docs/caddyfile/directives/basic_auth) for how to generate the password hash.
```
https://your-domain.com {
https://photos.example.com {
# Immich Public Proxy paths
@public path /share /share/* /s/*
handle @public {
+2 -2
View File
@@ -6,7 +6,7 @@ If you're using Cloudflare and videos do not play well, set your `/share/video/*
[this Cloudflare community thread](https://community.cloudflare.com/t/mp4-wont-load-in-safari-using-cloudflare/10587/48)
for the background.
<a href="/cloudflare-video-cache.webp"><img src="/cloudflare-video-cache.webp" style="width:70%" alt="Cloudflare cache bypass rule for video paths"></a>
<a href="/cloudflare-video-cache.webp"><img src="./public/cloudflare-video-cache.webp" style="width:70%" alt="Cloudflare cache bypass rule for video paths"></a>
## "Download all" fails partway through
@@ -86,7 +86,7 @@ Set `PUBLIC_BASE_URL` in your `docker-compose.yml` to the public address of IPP,
```yaml
environment:
PUBLIC_BASE_URL: https://your-proxy-url.com
PUBLIC_BASE_URL: https://photos.example.com
```
If you serve IPP from several domains, leave it unset and make sure your reverse proxy forwards the original `Host`
+2 -2
View File
@@ -53,7 +53,7 @@ services:
security_opt:
- no-new-privileges
environment:
PUBLIC_BASE_URL: https://your-proxy-url.com
PUBLIC_BASE_URL: https://photos.example.com
IMMICH_URL: http://your-internal-immich-server:2283
healthcheck:
test: curl -sf -m 4 http://localhost:3000/share/healthcheck -o /dev/null || exit 1
@@ -73,7 +73,7 @@ services:
- no-new-privileges
environment:
IMMICH_URL: http://your-internal-immich-server:2283
PUBLIC_BASE_URL: https://your-proxy-url.com
PUBLIC_BASE_URL: https://photos.example.com
healthcheck:
test: curl -sf -m 4 http://localhost:3000/healthcheck -o /dev/null || exit 1
start_period: 10s