docs: clarify BETTER_AUTH_URL should be origin only, not include base path

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

@@ -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)

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

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`}</code></pre>
               </div>
               <div class="bg-muted/30 rounded p-3 mt-3">
                 <pre class="text-sm"><code>{`# 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`}</code></pre>
+BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com
+# → Auth endpoints resolve to: https://git.example.com/mirror/api/auth/*`}</code></pre>
               </div>
               <ul class="mt-3 space-y-1 text-sm">
-                <li><code class="bg-red-500/10 px-1 rounded">BASE_URL</code> — Application base path for path-prefix deployments (e.g. <code>/mirror</code>)</li>
-                <li><code class="bg-red-500/10 px-1 rounded">BETTER_AUTH_URL</code> — Server-side auth base URL for callbacks and redirects</li>
-                <li><code class="bg-red-500/10 px-1 rounded">PUBLIC_BETTER_AUTH_URL</code> — Client-side (browser) URL for auth API calls</li>
+                <li><code class="bg-red-500/10 px-1 rounded">BASE_URL</code> — Application base path for path-prefix deployments (e.g. <code>/mirror</code>). This is handled separately from the auth URLs.</li>
+                <li><code class="bg-red-500/10 px-1 rounded">BETTER_AUTH_URL</code> — Server-side auth origin, scheme + host only (e.g. <code>https://git.example.com</code>). Do <strong>not</strong> include the base path — it is applied automatically from <code>BASE_URL</code>.</li>
+                <li><code class="bg-red-500/10 px-1 rounded">PUBLIC_BETTER_AUTH_URL</code> — Client-side (browser) auth origin. Same rule: origin only, no path.</li>
                 <li><code class="bg-red-500/10 px-1 rounded">BETTER_AUTH_TRUSTED_ORIGINS</code> — Comma-separated origins allowed to make auth requests</li>
               </ul>
             </div>