Skip to content

Commit eac6bbc

Browse files
committed
docs: [#253] add MySQL configuration guidance to manual testing docs
Added comprehensive MySQL configuration examples and guidance to help users understand how to configure MySQL instead of SQLite. Changes: - docs/e2e-testing/manual/README.md: Added MySQL configuration example with required fields (host, port, database_name, username, password) - docs/e2e-testing/manual/mysql-verification.md: Fixed example configuration to show complete structure with all required fields The previous example was incomplete and showed an incorrect structure with a separate 'database' section. The correct configuration embeds all MySQL settings under tracker.core.database.
1 parent 6171a6b commit eac6bbc

File tree

2 files changed

+121
-10
lines changed

2 files changed

+121
-10
lines changed

docs/e2e-testing/manual/README.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,77 @@ nano envs/manual-test.json
116116

117117
</details>
118118

119+
**Using MySQL Instead of SQLite**:
120+
121+
The default template uses SQLite (`driver: "sqlite3"`), which is suitable for testing and small deployments. To use MySQL instead, you need to provide additional database configuration fields:
122+
123+
<details>
124+
<summary>Click to expand MySQL configuration example</summary>
125+
126+
```json
127+
{
128+
"environment": {
129+
"name": "manual-test-mysql",
130+
"instance_name": null
131+
},
132+
"ssh_credentials": {
133+
"private_key_path": "fixtures/testing_rsa",
134+
"public_key_path": "fixtures/testing_rsa.pub",
135+
"username": "torrust",
136+
"port": 22
137+
},
138+
"provider": {
139+
"provider": "lxd",
140+
"profile_name": "torrust-profile-manual-test-mysql"
141+
},
142+
"tracker": {
143+
"core": {
144+
"database": {
145+
"driver": "mysql",
146+
"host": "mysql",
147+
"port": 3306,
148+
"database_name": "torrust_tracker",
149+
"username": "tracker_user",
150+
"password": "tracker_password"
151+
},
152+
"private": false
153+
},
154+
"udp_trackers": [
155+
{
156+
"bind_address": "0.0.0.0:6969"
157+
}
158+
],
159+
"http_trackers": [
160+
{
161+
"bind_address": "0.0.0.0:7070"
162+
}
163+
],
164+
"http_api": {
165+
"bind_address": "0.0.0.0:1212",
166+
"admin_token": "MyAccessToken"
167+
}
168+
}
169+
}
170+
```
171+
172+
</details>
173+
174+
**Required MySQL Fields**:
175+
176+
When `driver` is set to `"mysql"`, you must provide:
177+
178+
- `host` - MySQL hostname (use `"mysql"` for Docker Compose service name)
179+
- `port` - MySQL port (typically `3306`)
180+
- `database_name` - Name of the database to create
181+
- `username` - MySQL user for tracker connection
182+
- `password` - Password for the MySQL user
183+
184+
These credentials are used to:
185+
186+
1. Configure the MySQL Docker container (via docker-compose.yml)
187+
2. Configure the tracker to connect to MySQL
188+
3. Initialize the database schema
189+
119190
> **💡 Tip**: Always use `create template` to generate configuration files. This ensures you get the latest schema and prevents issues with outdated examples in documentation.
120191
121192
### Step 2: Create Environment

docs/e2e-testing/manual/mysql-verification.md

Lines changed: 50 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,30 +22,70 @@ Complete the standard deployment workflow first (see [Manual E2E Testing Guide](
2222
4. ✅ Software released
2323
5. ✅ Services running
2424

25-
**Your environment configuration must include MySQL**:
25+
**Your environment configuration must include MySQL database configuration**:
2626

2727
```json
2828
{
29+
"environment": {
30+
"name": "manual-test-mysql",
31+
"instance_name": null
32+
},
33+
"ssh_credentials": {
34+
"private_key_path": "fixtures/testing_rsa",
35+
"public_key_path": "fixtures/testing_rsa.pub",
36+
"username": "torrust",
37+
"port": 22
38+
},
39+
"provider": {
40+
"provider": "lxd",
41+
"profile_name": "torrust-profile-manual-test-mysql"
42+
},
2943
"tracker": {
3044
"core": {
3145
"database": {
3246
"driver": "mysql",
33-
"database_name": "torrust_tracker"
47+
"host": "mysql",
48+
"port": 3306,
49+
"database_name": "torrust_tracker",
50+
"username": "tracker_user",
51+
"password": "tracker_password"
52+
},
53+
"private": false
54+
},
55+
"udp_trackers": [
56+
{
57+
"bind_address": "0.0.0.0:6969"
58+
}
59+
],
60+
"http_trackers": [
61+
{
62+
"bind_address": "0.0.0.0:7070"
3463
}
64+
],
65+
"http_api": {
66+
"bind_address": "0.0.0.0:1212",
67+
"admin_token": "MyAccessToken"
3568
}
3669
},
37-
"database": {
38-
"driver": "mysql",
39-
"host": "mysql",
40-
"port": 3306,
41-
"database_name": "torrust_tracker",
42-
"username": "tracker_user",
43-
"password": "tracker_password",
44-
"root_password": "root_password"
70+
"prometheus": {
71+
"scrape_interval_in_secs": 15
72+
},
73+
"grafana": {
74+
"admin_user": "admin",
75+
"admin_password": "admin"
4576
}
4677
}
4778
```
4879

80+
**Required MySQL fields** (under `tracker.core.database`):
81+
82+
- `driver`: Must be `"mysql"`
83+
- `host`: MySQL hostname (`"mysql"` for Docker Compose service name)
84+
- `port`: MySQL port (typically `3306`)
85+
- `database_name`: Name of the database to create
86+
- `username`: MySQL user for tracker connection
87+
- `password`: Password for the MySQL user
88+
4989
## ⚠️ CRITICAL: Understanding File Locations
5090

5191
**There are TWO completely different JSON files with different purposes:**

0 commit comments

Comments
 (0)