From 4e100286691cd157dbfa271d49f154423435ce4f Mon Sep 17 00:00:00 2001
From: jubnl <jgunther021@gmail.com>
Date: Fri, 3 Apr 2026 03:51:29 +0200
Subject: [PATCH] document APP_URL usage

---
 README.md                      | 3 ++-
 chart/templates/configmap.yaml | 3 +++
 chart/values.yaml              | 3 +++
 docker-compose.yml             | 1 +
 4 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 572d849..0ede2c5 100644
--- a/README.md
+++ b/README.md
@@ -146,7 +146,7 @@ services:
       # - COOKIE_SECURE=false # Uncomment if accessing over plain HTTP (no HTTPS). Not recommended for production.
       - TRUST_PROXY=1 # Number of trusted proxies for X-Forwarded-For
       # - ALLOW_INTERNAL_NETWORK=true # Uncomment if Immich or other services are on your local network (RFC-1918 IPs)
-      - APP_URL=${APP_URL:-} # Base URL of this instance — required when OIDC is enabled; must match the redirect URI registered with your IdP
+      - APP_URL=${APP_URL:-} # Base URL of this instance — required when OIDC is enabled; must match the redirect URI registered with your IdP; Also used as the base URL for email notifications and other external links
       # - OIDC_ISSUER=https://auth.example.com # OpenID Connect provider URL
       # - OIDC_CLIENT_ID=trek # OpenID Connect client ID
       # - OIDC_CLIENT_SECRET=supersecret # OpenID Connect client secret
@@ -284,6 +284,7 @@ trek.yourdomain.com {
 | `COOKIE_SECURE` | Set to `false` to allow session cookies over plain HTTP (e.g. accessing via IP without HTTPS). Defaults to `true` in production. **Not recommended to disable in production.** | `true` |
 | `TRUST_PROXY` | Number of trusted reverse proxies for `X-Forwarded-For` | `1` |
 | `ALLOW_INTERNAL_NETWORK` | Allow outbound requests to private/RFC-1918 IP addresses. Set to `true` if Immich or other integrated services are hosted on your local network. Loopback (`127.x`) and link-local/metadata addresses (`169.254.x`) are always blocked regardless of this setting. | `false` |
+| `APP_URL` | Public base URL of this instance (e.g. `https://trek.example.com`). Required when OIDC is enabled — must match the redirect URI registered with your IdP. Also used as the base URL for external links in email notifications. | — |
 | **OIDC / SSO** | | |
 | `OIDC_ISSUER` | OpenID Connect provider URL | — |
 | `OIDC_CLIENT_ID` | OIDC client ID | — |
diff --git a/chart/templates/configmap.yaml b/chart/templates/configmap.yaml
index a7a4eb7..7322505 100644
--- a/chart/templates/configmap.yaml
+++ b/chart/templates/configmap.yaml
@@ -10,6 +10,9 @@ data:
   {{- if .Values.env.ALLOWED_ORIGINS }}
   ALLOWED_ORIGINS: {{ .Values.env.ALLOWED_ORIGINS | quote }}
   {{- end }}
+  {{- if .Values.env.APP_URL }}
+  APP_URL: {{ .Values.env.APP_URL | quote }}
+  {{- end }}
   {{- if .Values.env.ALLOW_INTERNAL_NETWORK }}
   ALLOW_INTERNAL_NETWORK: {{ .Values.env.ALLOW_INTERNAL_NETWORK | quote }}
   {{- end }}
diff --git a/chart/values.yaml b/chart/values.yaml
index 471dafa..9501c60 100644
--- a/chart/values.yaml
+++ b/chart/values.yaml
@@ -17,6 +17,9 @@ env:
   PORT: 3000
   # ALLOWED_ORIGINS: ""
   # NOTE: If using ingress, ensure env.ALLOWED_ORIGINS matches the domains in ingress.hosts for proper CORS configuration.
+  # APP_URL: "https://trek.example.com"
+  # Public base URL of this instance. Required when OIDC is enabled — must match the redirect URI registered with your IdP.
+  # Also used as the base URL for links in email notifications and other external links.
   # ALLOW_INTERNAL_NETWORK: "false"
   # Set to "true" if Immich or other integrated services are hosted on a private/RFC-1918 network address.
   # Loopback (127.x) and link-local/metadata addresses (169.254.x) are always blocked.
diff --git a/docker-compose.yml b/docker-compose.yml
index 768f73f..4645f2d 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -26,6 +26,7 @@ services:
 #     - COOKIE_SECURE=false # Uncomment if accessing over plain HTTP (no HTTPS). Not recommended for production.
       - TRUST_PROXY=1 # Number of trusted proxies (for X-Forwarded-For / real client IP)
       - ALLOW_INTERNAL_NETWORK=false # Set to true if Immich or other services are hosted on your local network (RFC-1918 IPs). Loopback and link-local addresses remain blocked regardless.
+#      - APP_URL=https://trek.example.com # Public base URL — required when OIDC is enabled (must match the redirect URI registered with your IdP); also used as base URL for links in email notifications
 #      - OIDC_ISSUER=https://auth.example.com # OpenID Connect provider URL
 #      - OIDC_CLIENT_ID=trek # OpenID Connect client ID
 #      - OIDC_CLIENT_SECRET=supersecret # OpenID Connect client secret