Skip to content

Commit 51237d4

Browse files
s0up4200s0up4200
authored
docs: Add configuration reference (#1440)
1 parent 46814aa commit 51237d4

5 files changed

Lines changed: 107 additions & 4 deletions

File tree

‎documentation/docs/configuration/base-url.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 2
2+
sidebar_position: 3
33
title: Base URL
44
---
55

‎documentation/docs/configuration/cli-commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 5
33
title: CLI Commands
44
---
55

‎documentation/docs/configuration/environment.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
---
2-
sidebar_position: 1
2+
sidebar_position: 2
33
title: Environment Variables
44
---
55

66
# Environment Variables
77

88
Configuration is stored in `config.toml` (created automatically on first run, or manually with `qui generate-config`). You can also use environment variables:
99

10+
For the complete list (including `config.toml` keys, defaults, and notes), see [Configuration Reference](./reference).
11+
1012
## Server
1113

1214
```bash
@@ -39,6 +41,12 @@ When `logPath` is set the server writes to disk using size-based rotation. Adjus
3941
QUI__DATA_DIR=... # Optional: custom data directory (default: next to config)
4042
```
4143

44+
## Cross-Seed
45+
46+
```bash
47+
QUI__CROSS_SEED_RECOVER_ERRORED_TORRENTS=false # Optional: recover errored/missingFiles torrents; can add ~25+ minutes per torrent (default: false)
48+
```
49+
4250
## Tracker Icons
4351

4452
```bash
@@ -51,6 +59,12 @@ QUI__TRACKER_ICONS_FETCH_ENABLED=false # Optional: set to false to disable remo
5159
QUI__CHECK_FOR_UPDATES=false # Optional: disable update checks and UI indicators (default: true)
5260
```
5361

62+
## Profiling (pprof)
63+
64+
```bash
65+
QUI__PPROF_ENABLED=true # Optional: enable pprof server on :6060 (default: false)
66+
```
67+
5468
## Metrics
5569

5670
```bash

‎documentation/docs/configuration/oidc.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 4
33
title: OIDC
44
---
55

66
# OpenID Connect (OIDC)
77

88
Set `QUI__OIDC_ENABLED=true` to hand authentication off to an external identity provider. The built-in login screen automatically offers a "Sign in with OIDC" button when the backend detects a valid OIDC configuration.
99

10+
For the full mapping (TOML keys + environment variables + defaults), see [Configuration Reference](./reference).
11+
1012
## Configuration Options
1113

1214
| Variable | Description |

‎documentation/docs/configuration/reference.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
sidebar_position: 1
3+
title: Configuration Reference
4+
---
5+
6+
# Configuration Reference
7+
8+
qui supports configuration via:
9+
10+
- `config.toml` (auto-created on first run, or manually via `qui generate-config`)
11+
- environment variables (`QUI__...`) to override `config.toml`
12+
13+
This page documents both in one place.
14+
15+
## Precedence
16+
17+
Highest wins:
18+
19+
1. `QUI__*_FILE` (for supported secrets)
20+
2. `QUI__*` environment variables
21+
3. `config.toml`
22+
4. built-in defaults
23+
24+
## Config File Location
25+
26+
Default `config.toml` locations:
27+
28+
- Linux/macOS: `~/.config/qui/config.toml`
29+
- Windows: `%APPDATA%\\qui\\config.toml`
30+
31+
Override with `--config-dir`:
32+
33+
- directory path: `--config-dir /path/to/config/` (uses `/path/to/config/config.toml`)
34+
- file path (back-compat): `--config-dir /path/to/custom.toml`
35+
36+
## Notes On Reloading
37+
38+
qui watches `config.toml` for changes. Some settings are applied immediately (for example logging and tracker icon fetching). For anything else, restart qui after changes to be safe.
39+
40+
## Settings
41+
42+
| TOML key | Environment variable | Type | Default | Notes |
43+
|---|---|---:|---|---|
44+
| `host` | `QUI__HOST` | string | `localhost` (or `0.0.0.0` in containers) | Bind address for the main HTTP server. |
45+
| `port` | `QUI__PORT` | int | `7476` | Port for the main HTTP server. |
46+
| `baseUrl` | `QUI__BASE_URL` | string | `/` | Serve qui from a subdirectory (example: `/qui/`). |
47+
| `sessionSecret` | `QUI__SESSION_SECRET` / `QUI__SESSION_SECRET_FILE` | string | auto-generated | WARNING: changing breaks decryption of stored instance passwords; you must re-enter them in the UI. |
48+
| `logLevel` | `QUI__LOG_LEVEL` | string | `INFO` | `ERROR`, `DEBUG`, `INFO`, `WARN`, `TRACE`. Applied immediately. |
49+
| `logPath` | `QUI__LOG_PATH` | string | empty | If empty: logs to stdout. Relative paths resolve relative to the config directory. Applied immediately. |
50+
| `logMaxSize` | `QUI__LOG_MAX_SIZE` | int | `50` | MiB threshold before rotation. Applied immediately. |
51+
| `logMaxBackups` | `QUI__LOG_MAX_BACKUPS` | int | `3` | Rotated files retained. `0` keeps all. Applied immediately. |
52+
| `dataDir` | `QUI__DATA_DIR` | string | empty | If empty: uses the directory containing `config.toml`. Database `qui.db` lives here. Restart recommended. |
53+
| `checkForUpdates` | `QUI__CHECK_FOR_UPDATES` | bool | `true` | Controls update checks and UI indicators. Restart recommended. |
54+
| `trackerIconsFetchEnabled` | `QUI__TRACKER_ICONS_FETCH_ENABLED` | bool | `true` | Disable to prevent remote tracker favicon fetches. Applied immediately. |
55+
| `crossSeedRecoverErroredTorrents` | `QUI__CROSS_SEED_RECOVER_ERRORED_TORRENTS` | bool | `false` | When enabled, cross-seed automation attempts recovery (pause, recheck, resume) for errored/missingFiles torrents. Can add 25+ minutes per torrent. Restart recommended. |
56+
| `pprofEnabled` | `QUI__PPROF_ENABLED` | bool | `false` | Enables pprof server on `:6060` (`/debug/pprof/`). Restart required. |
57+
| `metricsEnabled` | `QUI__METRICS_ENABLED` | bool | `false` | Enables a Prometheus metrics server (separate port). Restart required. |
58+
| `metricsHost` | `QUI__METRICS_HOST` | string | `127.0.0.1` | Metrics server bind address. Restart required. |
59+
| `metricsPort` | `QUI__METRICS_PORT` | int | `9074` | Metrics server port. Restart required. |
60+
| `metricsBasicAuthUsers` | `QUI__METRICS_BASIC_AUTH_USERS` | string | empty | Optional basic auth: `user:bcrypt_hash` or `user1:hash1,user2:hash2`. Restart required. |
61+
| `externalProgramAllowList` | (none) | string[] | empty list | Restricts which executables can be launched from the UI. Only configurable via `config.toml` (no env override). |
62+
| `oidcEnabled` | `QUI__OIDC_ENABLED` | bool | `false` | Enable OpenID Connect authentication. Restart required. |
63+
| `oidcIssuer` | `QUI__OIDC_ISSUER` | string | empty | OIDC issuer URL. Restart required. |
64+
| `oidcClientId` | `QUI__OIDC_CLIENT_ID` | string | empty | OIDC client ID. Restart required. |
65+
| `oidcClientSecret` | `QUI__OIDC_CLIENT_SECRET` / `QUI__OIDC_CLIENT_SECRET_FILE` | string | empty | OIDC client secret. Restart required. |
66+
| `oidcRedirectUrl` | `QUI__OIDC_REDIRECT_URL` | string | empty | Must match the provider redirect URI (include `baseUrl` when reverse proxying). Restart required. |
67+
| `oidcDisableBuiltInLogin` | `QUI__OIDC_DISABLE_BUILT_IN_LOGIN` | bool | `false` | Hide local username/password form when OIDC is enabled. Restart required. |
68+
69+
## Example `config.toml`
70+
71+
```toml
72+
host = "0.0.0.0"
73+
port = 7476
74+
baseUrl = "/qui/"
75+
76+
logLevel = "INFO"
77+
logPath = "log/qui.log"
78+
logMaxSize = 50
79+
logMaxBackups = 3
80+
81+
trackerIconsFetchEnabled = false
82+
83+
externalProgramAllowList = [
84+
"/usr/local/bin",
85+
"/home/user/bin/my-script",
86+
]
87+
```

0 commit comments

Comments
 (0)