From 8fac30fc022c37fdaa1afc0d91802a2495539db2 Mon Sep 17 00:00:00 2001 From: Arunavo Ray Date: Thu, 9 Apr 2026 20:11:00 +0530 Subject: [PATCH] docs: clarify BETTER_AUTH_URL should be origin only, not include base path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update README, ENVIRONMENT_VARIABLES.md, and advanced docs page to explicitly state that BETTER_AUTH_URL and PUBLIC_BETTER_AUTH_URL must be origin only (scheme + host). The BASE_URL path prefix is applied automatically — any path accidentally included is stripped. --- README.md | 5 ++++- docs/ENVIRONMENT_VARIABLES.md | 9 ++++++--- src/pages/docs/advanced.astro | 12 +++++++----- 3 files changed, 17 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6660da4..5b92f8c 100644 --- a/README.md +++ b/README.md @@ -303,15 +303,18 @@ CLEANUP_DRY_RUN=false # Set to true to test without changes If you run behind a reverse proxy on a subpath (for example `https://git.example.com/mirror`), configure: ```bash +# BASE_URL handles the path prefix — auth URLs stay as origin only BASE_URL=/mirror BETTER_AUTH_URL=https://git.example.com PUBLIC_BETTER_AUTH_URL=https://git.example.com BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com +# → Auth endpoints resolve to: https://git.example.com/mirror/api/auth/* ``` Notes: - `BASE_URL` sets the application path prefix. -- `BETTER_AUTH_TRUSTED_ORIGINS` should contain origins only (no path). +- `BETTER_AUTH_URL` and `PUBLIC_BETTER_AUTH_URL` should be **origin only** (e.g. `https://git.example.com`). Do not include the base path — it is applied automatically from `BASE_URL`. Any path accidentally included is stripped. +- `BETTER_AUTH_TRUSTED_ORIGINS` should also contain origins only (no path). - `BASE_URL` is runtime configuration, so prebuilt registry images can be reused across different subpaths. ### Mirror Token Rotation (GitHub Token Changed) diff --git a/docs/ENVIRONMENT_VARIABLES.md b/docs/ENVIRONMENT_VARIABLES.md index 533b218..4306c52 100644 --- a/docs/ENVIRONMENT_VARIABLES.md +++ b/docs/ENVIRONMENT_VARIABLES.md @@ -36,8 +36,8 @@ Essential application settings required for running Gitea Mirror. | `BASE_URL` | Application base path. Use `/` for root deployments, or a prefix such as `/mirror` when serving behind a reverse-proxy path prefix. | `/` | No | | `DATABASE_URL` | Database connection URL | `sqlite://data/gitea-mirror.db` | No | | `BETTER_AUTH_SECRET` | Secret key for session signing (generate with: `openssl rand -base64 32`) | - | Yes | -| `BETTER_AUTH_URL` | Primary base URL for authentication. This should be the main URL where your application is accessed. | `http://localhost:4321` | No | -| `PUBLIC_BETTER_AUTH_URL` | Client-side auth URL for multi-origin access. Set this to your primary domain when you need to access the app from different origins (e.g., both IP and domain). The client will use this URL for all auth requests instead of the current browser origin. | - | No | +| `BETTER_AUTH_URL` | Authentication origin (scheme + host only, e.g. `https://git.example.com`). Do **not** include a path — any path is automatically stripped, and `BASE_URL` is applied separately. | `http://localhost:4321` | No | +| `PUBLIC_BETTER_AUTH_URL` | Client-side auth origin for multi-origin access (same rule: origin only, no path). Set this to your primary domain when you need to access the app from different origins (e.g., both IP and domain). The client will use this URL for all auth requests instead of the current browser origin. | - | No | | `BETTER_AUTH_TRUSTED_ORIGINS` | Trusted origins for authentication requests. Comma-separated list of URLs. Use this to specify additional access URLs (e.g., local IP + domain: `http://10.10.20.45:4321,https://gitea-mirror.mydomain.tld`), SSO providers, reverse proxies, etc. | - | No | | `ENCRYPTION_SECRET` | Optional encryption key for tokens (generate with: `openssl rand -base64 48`) | - | No | @@ -377,14 +377,17 @@ This setup allows you to: If you serve Gitea Mirror under a subpath such as `https://git.example.com/mirror`, set: ```bash +# BASE_URL handles the path prefix — auth URLs stay as origin only BASE_URL=/mirror BETTER_AUTH_URL=https://git.example.com PUBLIC_BETTER_AUTH_URL=https://git.example.com BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com +# → Auth endpoints resolve to: https://git.example.com/mirror/api/auth/* ``` Notes: -- `BETTER_AUTH_TRUSTED_ORIGINS` must contain origins only (no path). +- `BETTER_AUTH_URL` and `PUBLIC_BETTER_AUTH_URL` must be **origin only** (scheme + host). Do not include the base path — it is applied automatically from `BASE_URL`. Any path accidentally included is stripped. +- `BETTER_AUTH_TRUSTED_ORIGINS` must also contain origins only (no path). - `BASE_URL` is applied at runtime, so prebuilt images can be reused with different path prefixes. ### Trusted Origins diff --git a/src/pages/docs/advanced.astro b/src/pages/docs/advanced.astro index ff9302f..cbcdd2d 100644 --- a/src/pages/docs/advanced.astro +++ b/src/pages/docs/advanced.astro @@ -54,7 +54,7 @@ import { withBase } from '@/lib/base-path'; { var: 'HOST', desc: 'Server host', default: '0.0.0.0' }, { var: 'BASE_URL', desc: 'Application base path ("/" or e.g. "/mirror")', default: '/' }, { var: 'BETTER_AUTH_SECRET', desc: 'Authentication secret key', default: 'Auto-generated' }, - { var: 'BETTER_AUTH_URL', desc: 'Authentication base URL', default: 'http://localhost:4321' }, + { var: 'BETTER_AUTH_URL', desc: 'Authentication origin (scheme + host, no path). Any path is stripped automatically.', default: 'http://localhost:4321' }, { var: 'NODE_EXTRA_CA_CERTS', desc: 'Path to CA certificate file', default: 'None' }, { var: 'DATABASE_URL', desc: 'SQLite database path', default: './data/gitea-mirror.db' }, ].map((item, i) => ( @@ -230,15 +230,17 @@ BETTER_AUTH_TRUSTED_ORIGINS=https://gitea-mirror.example.com`} 
{`# If deployed under a path prefix (example: /mirror):
+# BASE_URL handles the path — auth URLs stay as origin only
 BASE_URL=/mirror
 BETTER_AUTH_URL=https://git.example.com
 PUBLIC_BETTER_AUTH_URL=https://git.example.com
-BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com`}
+BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com +# → Auth endpoints resolve to: https://git.example.com/mirror/api/auth/*`}