From 729526bd34871aeb6c6da7a6dd266cd5463350b9 Mon Sep 17 00:00:00 2001 From: luojiyin Date: Thu, 9 Apr 2026 11:49:53 +0800 Subject: [PATCH] docs: Clarify FORCE_HTTPS and TRUST_PROXY configuration - Add explicit warning about FORCE_HTTPS when accessing directly on http://host:3000 - Explain that FORCE_HTTPS=false is required for direct access without reverse proxy - Clarify TRUST_PROXY usage only when behind actual reverse proxy - Prevent common configuration issues causing infinite redirects This resolves potential confusion where users might experience 301 redirects to non-existent HTTPS endpoints when accessing the Docker container directly. --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 49d844f..f942d54 100644 --- a/README.md +++ b/README.md @@ -174,6 +174,8 @@ services: start_period: 15s ``` +This example is aimed at reverse-proxy deployments. If you access TREK directly on `http://:3000` without nginx, Caddy, Traefik, or another TLS-terminating proxy in front of it, set `FORCE_HTTPS=false` and remove `TRUST_PROXY` to avoid redirects to a non-existent HTTPS endpoint. + ```bash docker compose up -d ``` @@ -283,9 +285,9 @@ trek.yourdomain.com { | `TZ` | Timezone for logs, reminders and cron jobs (e.g. `Europe/Berlin`) | `UTC` | | `LOG_LEVEL` | `info` = concise user actions, `debug` = verbose details | `info` | | `ALLOWED_ORIGINS` | Comma-separated origins for CORS and email links | same-origin | -| `FORCE_HTTPS` | Redirect HTTP to HTTPS behind a TLS-terminating proxy | `false` | +| `FORCE_HTTPS` | Redirect HTTP to HTTPS behind a TLS-terminating proxy. If you access TREK directly on `http://host:3000`, keep this `false`. | `false` | | `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` | +| `TRUST_PROXY` | Number of trusted reverse proxies for `X-Forwarded-For`. Use this only when TREK is actually behind a reverse proxy. | `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** | | |