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. 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. 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 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. 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. 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. 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. `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 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. - 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. - 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. - 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. while loading.
- Types and defaults come from `app/config.json` and `upload-app/config.json`. The build checks them; see - Types and defaults come from `app/config.json` and `upload-app/config.json`. The build checks them; see
[Config reference pages](#config-reference-pages). [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 **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 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. 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 ```yaml
environment: environment:
PUBLIC_BASE_URL: https://your-proxy-url.com PUBLIC_BASE_URL: https://photos.example.com
IMMICH_URL: http://your-internal-immich-server:2283 IMMICH_URL: http://your-internal-immich-server:2283
CONFIG: | 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 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: 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 ## Share links
A standard link looks like `https://your-proxy-url.com/share/<key>`, where the key is the shared link's public ID 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://your-proxy-url.com/s/<slug>` 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). instead. Slug links can be turned off with [`allowSlugLinks`](/config/ipp-options#allowsluglinks).
The settings on the shared link in Immich are respected: 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. 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 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). 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. 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`. 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 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 6. Set the "External domain" in your Immich **Server Settings** to be whatever domain you use to publicly serve
Immich Public Proxy: 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 Now whenever you share an image or gallery through Immich, it will automatically create the correct public path for
you. 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: 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 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 **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. what photos or videos are shared in that share URL.
+5 -5
View File
@@ -16,7 +16,7 @@ server:
- name: gateway - name: gateway
namespace: kube-system namespace: kube-system
hostnames: hostnames:
- your-immich-url.com - immich.example.com
rules: rules:
- backendRefs: - backendRefs:
- name: immich-server-main - name: immich-server-main
@@ -28,7 +28,7 @@ server:
- name: gateway - name: gateway
namespace: kube-system namespace: kube-system
hostnames: hostnames:
- your-proxy-url.com - photos.example.com
rules: rules:
- backendRefs: - backendRefs:
- name: immich-server-immich-public-proxy - name: immich-server-immich-public-proxy
@@ -44,7 +44,7 @@ server:
pullPolicy: IfNotPresent pullPolicy: IfNotPresent
env: env:
IMMICH_URL: http://immich-server-main:2283 # the in-cluster Immich service, not your public URL 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 # Optional lockdown: IPP writes nothing to disk and needs no extra privileges
securityContext: securityContext:
readOnlyRootFilesystem: true readOnlyRootFilesystem: true
@@ -80,7 +80,7 @@ server:
enabled: true enabled: true
hosts: hosts:
- host: your-immich-url.com - host: immich.example.com
paths: paths:
- path: / - path: /
pathType: Prefix pathType: Prefix
@@ -89,7 +89,7 @@ server:
immich-public-proxy: immich-public-proxy:
enabled: true enabled: true
hosts: hosts:
- host: your-proxy-url.com - host: photos.example.com
paths: paths:
- path: / - path: /
pathType: Prefix 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. [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 # Immich Public Proxy paths
@public path /share /share/* /s/* @public path /share /share/* /s/*
handle @public { 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) [this Cloudflare community thread](https://community.cloudflare.com/t/mp4-wont-load-in-safari-using-cloudflare/10587/48)
for the background. 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 ## "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 ```yaml
environment: 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` 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: security_opt:
- no-new-privileges - no-new-privileges
environment: environment:
PUBLIC_BASE_URL: https://your-proxy-url.com PUBLIC_BASE_URL: https://photos.example.com
IMMICH_URL: http://your-internal-immich-server:2283 IMMICH_URL: http://your-internal-immich-server:2283
healthcheck: healthcheck:
test: curl -sf -m 4 http://localhost:3000/share/healthcheck -o /dev/null || exit 1 test: curl -sf -m 4 http://localhost:3000/share/healthcheck -o /dev/null || exit 1
@@ -73,7 +73,7 @@ services:
- no-new-privileges - no-new-privileges
environment: environment:
IMMICH_URL: http://your-internal-immich-server:2283 IMMICH_URL: http://your-internal-immich-server:2283
PUBLIC_BASE_URL: https://your-proxy-url.com PUBLIC_BASE_URL: https://photos.example.com
healthcheck: healthcheck:
test: curl -sf -m 4 http://localhost:3000/healthcheck -o /dev/null || exit 1 test: curl -sf -m 4 http://localhost:3000/healthcheck -o /dev/null || exit 1
start_period: 10s start_period: 10s