Skip to content

Commit 10fc093

Browse files
Alfagun74Alfagun74
committed
docs
1 parent 9fc38bd commit 10fc093

File tree

3 files changed

+127
-38
lines changed

3 files changed

+127
-38
lines changed

‎docs/server-docs/configuration.md‎

Lines changed: 120 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,111 @@ sidebar_position: 2
88
Check out [configuration.ts](https://github.com/Phalcode/gamevault-backend/blob/master/src/configuration.ts) for all possible environment variables in case we forgot to update this page.
99
:::
1010

11-
All configuration properties of your GameVault server are passed as environment variables or via a .env file. The following tables describe the available properties, their default values, explanations, and possible values.
11+
## Three Ways to Configure GameVault
1212

13-
## Configuration Properties
13+
### 1. Environment Variables (Most Common)
1414

15-
This page describes the various configuration properties used in the application. These properties can be configured in the environment variables or in a `.env` file.
15+
Set variables directly via Docker Compose, `.env` files, or shell:
1616

17-
### SERVER
17+
```yaml
18+
# Docker Compose example
19+
environment:
20+
SERVER_PORT: 8080
21+
DB_HOST: postgres
22+
DB_PASSWORD: mypassword
23+
```
24+
25+
```bash
26+
# .env file example
27+
SERVER_PORT=8080
28+
DB_HOST=postgres
29+
DB_PASSWORD=mypassword
30+
```
31+
32+
### 2. Docker Secrets (`_FILE` method) — For Sensitive Values
33+
34+
Store secrets in files and reference them. Ideal for passwords, API keys, and tokens:
35+
36+
```yaml
37+
# docker-compose.yml
38+
secrets:
39+
db_password:
40+
file: ./secrets/db_password.txt
41+
environment:
42+
DB_PASSWORD_FILE: /run/secrets/db_password
43+
```
44+
45+
GameVault reads the file at runtime, keeping secrets out of logs and configs.
46+
47+
### 3. YAML Configuration Files — For Complex Setups
48+
49+
Create `config.yaml` or `config.yml` in your config volume (`VOLUMES_CONFIG`) for organized, readable configuration:
50+
51+
```yaml
52+
# config.yaml (case-insensitive, supports nested or flat syntax)
53+
server:
54+
port: 8080
55+
log_level: info
56+
db:
57+
system: POSTGRESQL
58+
host: postgres
59+
port: 5432
60+
```
61+
62+
Or use flat naming:
63+
64+
```yaml
65+
SERVER_PORT: 8080
66+
SERVER_LOG_LEVEL: info
67+
DB_SYSTEM: POSTGRESQL
68+
DB_HOST: postgres
69+
```
70+
71+
## Which Method Should I Use?
72+
73+
| Scenario | Method | Example |
74+
|----------|--------|----------|
75+
| Simple setup, few variables | Environment Variables | Docker Compose `environment:` block |
76+
| Passwords and secrets | Docker Secrets (`_FILE`) | `DB_PASSWORD_FILE: /run/secrets/db_password` |
77+
| Complex setup, many variables | YAML | Create `config.yaml` in `/config` volume |
78+
| Mixing all three | See **Precedence** below | Secrets override env, env overrides YAML |
79+
80+
## Configuration Precedence (Priority Order)
81+
82+
When a setting exists in multiple places, GameVault uses values in this order (highest → lowest):
83+
84+
1. **`VARIABLE_FILE`** (Docker Secrets file content) — *Always wins*
85+
2. **`VARIABLE`** (environment variable) — *Overrides YAML*
86+
3. **YAML file** (`config.yaml` / `config.yml`) — *Overrides defaults*
87+
4. **Built-in default** — *Used if nothing else is set*
88+
89+
### Real-World Example
90+
91+
If you set the same value in all three places:
92+
93+
```yaml
94+
# .env file or docker-compose environment:
95+
DB_PASSWORD=env-password
96+
97+
# config.yaml:
98+
db:
99+
password: yaml-password
100+
101+
# Docker secret:
102+
DB_PASSWORD_FILE: /run/secrets/db_password (contains "secret-password")
103+
```
104+
105+
**GameVault will use:** `secret-password` (from `_FILE`, highest priority)
106+
107+
If you remove the `_FILE`, it uses the **environment** value: `env-password`
108+
109+
If you remove the environment variable too, it uses **YAML**: `yaml-password`
110+
111+
## All Configuration Options
112+
113+
Below are all available configuration variables, organized by category.
114+
115+
### SERVER — Core Server Settings
18116

19117
| Property | Description | Default | Possible Values |
20118
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------- |
@@ -39,26 +137,26 @@ This page describes the various configuration properties used in the application
39137
| `SERVER_HTTPS_CERT_PATH` | The file path to the TLS certificate used for HTTPS. | - | Any valid file path |
40138
| `SERVER_HTTPS_CA_CERT_PATH` | The file path to the CA certificate used for HTTPS (e.g. for client certificate verification). | - | Any valid file path |
41139

42-
### WEB UI
140+
### WEB UI — Web Interface Settings
43141

44142
| Property | Description | Default | Possible Values |
45143
| ---------------- | ------------------------------------------------------------ | ------- | --------------- |
46144
| `WEB_UI_ENABLED` | Whether or not the web ui should be used. | `true` | `true`, `false` |
47145
| `WEB_UI_VERSION` | You can force a specific web ui version using this property. | - | `e.g. 16.0.0` |
48146

49-
### VOLUMES
147+
### VOLUMES — Storage Folder Paths
50148

51149
| Property | Description | Default | Possible Values |
52150
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------- |
53-
| `VOLUMES_CONFIG` | Folder inside container used for configuring GameVault. | `/config` | Any valid folder path |
151+
| `VOLUMES_CONFIG` | Folder used for configuring GameVault (for example `news.md`, `config.yaml`, and `config.yml`). Relative paths are supported, but absolute paths are recommended. | `/config` | Any valid folder path |
54152
| `VOLUMES_FILES` | Folder inside container used for game files. The server needs **write permissions** on this folder for the upload and delete game APIs to work. | `/files` | Any valid folder path |
55153
| `VOLUMES_MEDIA` | Folder inside container used for media. | `/media` | Any valid folder path |
56154
| `VOLUMES_SAVEFILES` | Folder inside container used for savefile uploads. | `/savefiles` | Any valid folder path |
57155
| `VOLUMES_LOGS` | Folder inside container used for logs. | `/logs` | Any valid folder path |
58156
| `VOLUMES_SQLITEDB` | Folder inside container used for `SQLITE` database. (Not needed if `DB_SYSTEM` is set to `POSTGRESQL`) | `/db` | Any valid folder path |
59157
| `VOLUMES_PLUGINS` | Folder inside container used for plugins. | `/plugins` | Any valid folder path |
60158

61-
### DB
159+
### DB — Database Configuration
62160

63161
| Property | Description | Default | Possible Values |
64162
| ------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------ | ----------------------- |
@@ -76,7 +174,7 @@ This page describes the various configuration properties used in the application
76174
| `DB_TLS_CERTIFICATE_PATH` | The file path to the TLS certificate used for authenticating the database server. | - | Any file path |
77175
| `DB_TLS_CA_CERTIFICATE_PATH` | The file path to the CA certificate used for verifying client certificates in TLS connections. | - | Any file path |
78176

79-
### USERS
177+
### USERS — User Registration & Requirements
80178

81179
| Property | Description | Default | Possible Values |
82180
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- |
@@ -85,14 +183,14 @@ This page describes the various configuration properties used in the application
85183
| `USERS_REQUIRE_LAST_NAME` | Require **Last Name** for new registrations. | `false` | `true`, `false` |
86184
| `USERS_REQUIRE_BIRTH_DATE` | Require **Birth Date** for new registrations. (**Automatically set to `true` when `PARENTAL_AGE_RESTRICTION_ENABLED` is true**) | `false` | `true`, `false` |
87185

88-
### PARENTAL
186+
### PARENTAL — Parental Control & Age Restrictions
89187

90188
| Property | Description | Default | Possible Values |
91189
| ---------------------------------- | ------------------------------------------------------------------------------------------- | ------- | --------------- |
92190
| `PARENTAL_AGE_RESTRICTION_ENABLED` | Determines whether age-based parental restrictions are enforced. | `false` | `true`, `false` |
93191
| `PARENTAL_AGE_OF_MAJORITY` | The age at which an individual is legally recognized as an adult for parental restrictions. | `18` | Any number |
94192

95-
### GAMES
193+
### GAMES — Game Library & Upload Settings
96194

97195
| Property | Description | Default | Possible Values |
98196
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------ |
@@ -105,7 +203,7 @@ This page describes the various configuration properties used in the application
105203
| `GAMES_WINDOWS_SETUP_DEFAULT_INSTALL_PARAMETERS` | Default command-line parameters used for Windows application setup files. These are used to attempt a silent installation. | `/D="%INSTALLDIR%" /S /DIR="%INSTALLDIR%" /SILENT /COMPONENTS=text` | Any string |
106204
| `GAMES_MAX_UPLOAD_SIZE` | The maximum file size allowed for game uploads via the API. Set it to 0 to disable game uploads. | `50 gb` | e.g. "50 gb", "100 gb", "1 tb" |
107205

108-
### MEDIA
206+
### MEDIA — Image & Media Upload Settings
109207

110208
| Property | Description | Default | Possible Values |
111209
| ------------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------- | ----------------------------------- |
@@ -114,15 +212,15 @@ This page describes the various configuration properties used in the application
114212
| `MEDIA_GC_DISABLED` | Whether or not media garbage collection is enabled. (Deletes unused media) | `false` | `true`, `false` |
115213
| `MEDIA_GC_INTERVAL_IN_MINUTES` | The interval in minutes for media garbage collection. | `60` | Any number |
116214

117-
### SAVEFILES
215+
### SAVEFILES — Game Save File Management
118216

119217
| Property | Description | Default | Possible Values |
120218
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------ |
121219
| `SAVEFILES_ENABLED` | Enables or disables savefile uploads. You may need to set up a volume for savefiles for them to persist. | `false` | `true`, `false` |
122220
| `SAVEFILES_MAX_SIZE` | Sets the maximum size for savefile uploads. | `1 gb` | e.g. "10 mb", "5 gb", "300 kb" |
123221
| `SAVEFILES_MAX_SAVES` | Sets the maximum number of savefiles per game and per user. Once this limit is reached, the oldest savefile will be deleted on the next upload. | `10` | Any number |
124222

125-
### METADATA
223+
### METADATA — Game Information Providers
126224

127225
| Property | Description | Default | Possible Values |
128226
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------ |
@@ -133,7 +231,7 @@ This page describes the various configuration properties used in the application
133231
| `METADATA_IGDB_CLIENT_ID` | The Client-ID used for authenticating requests to the IGDB API. | - | Your Client ID |
134232
| `METADATA_IGDB_CLIENT_SECRET` | The Client-Secret used for authenticating requests to the IGDB API. | - | Your Client Secret |
135233

136-
### AUTH
234+
### AUTH — Authentication & Login Methods
137235

138236
| Property | Description | Default | Possible Values |
139237
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------- |
@@ -151,7 +249,7 @@ This page describes the various configuration properties used in the application
151249
| `AUTH_OAUTH2_CLIENT_ID` | The OAuth2 client ID. | - | Any string |
152250
| `AUTH_OAUTH2_CLIENT_SECRET` | The OAuth2 client secret. | - | Any string |
153251

154-
### TESTING
252+
### TESTING — Development & Testing Options
155253

156254
| Property | Description | Default | Possible Values |
157255
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- |
@@ -161,25 +259,11 @@ This page describes the various configuration properties used in the application
161259
| `TESTING_MOCK_PROVIDERS` | If `true`, the server will create two mock providers. (-9999 and 9999 Priority) Useful for testing metadata-merges. | `false` | `true`, `false` |
162260
| `TESTING_LOG_HTTP_TRAFFIC_ENABLED` | If `true`, the server will log all incoming and outgoing HTTP traffic. (Except Healthchecks) | `false` | `true`, `false` |
163261

164-
## Docker Secrets Support
165-
166-
GameVault supports [Docker Secrets](https://docs.docker.com/compose/how-tos/use-secrets/) for **all** environment variables. Instead of passing a value directly as an environment variable, you can append `_FILE` to the variable name and set it to the path of a file containing the value.
167-
168-
For example, instead of:
169-
170-
```yaml
171-
environment:
172-
DB_PASSWORD: my-secret-password
173-
```
174-
175-
You can use:
262+
---
176263

177-
```yaml
178-
secrets:
179-
db_password:
180-
file: ./secrets/db_password.txt
181-
environment:
182-
DB_PASSWORD_FILE: /run/secrets/db_password
183-
```
264+
## Tips & Troubleshooting
184265

185-
The server will read the file contents and use them as the value for the variable. If both the variable and its `_FILE` variant are set, the `_FILE` variant takes priority.
266+
- **Confused about precedence?** See the real-world example under [Configuration Precedence](#configuration-precedence-priority-order) above.
267+
- **Using relative paths?** Relative paths in `VOLUMES_CONFIG` work but absolute paths are recommended for clarity.
268+
- **YAML not being read?** Ensure the file is named exactly `config.yaml` or `config.yml` and is in your `VOLUMES_CONFIG` folder.
269+
- **Secrets not working?** Make sure the file path in `VARIABLE_FILE` exists and contains the secret value (with no extra whitespace).

0 commit comments

Comments
 (0)