This is a dashboard that allows you to query and visualize data that the The Battle for Wesnoth Project collects about multiplayer games played on the official server. The live app can be viewed at https://replays.wesnoth.org/dashboard/.
See user_guide.md for a detailed user guide.
Python 3.11.5 was used to initially develop the app. To guarantee compatibility, it is recommended to use Python 3.11.5 or higher. You may use a virtual environment to isolate the Python version and app dependencies from other Python projects on your system.
A test was done to see if the app will work on Python 3.9.2. In debug mode, the app works but there is an error message, which the user doesn't see, that gets logged the first time the page was loaded, but the whole app works otherwise. With debug mode set to False, there is no error message at all.
Install development dependencies using
pip install -r requirements/development.txtIf you are having issues installing the mariadb dependency, see Install MariaDB Connector/Python.
The app fetches raw data from a MariaDB database. For development purposes, you need to install and run your own local MariaDB server instance. A .sql file containing a three-day sample from the actual database is provided in tests/three_days_sample_data.sql. You can use this file to create a local database for the app to read. The definitions of what the tables and columns in the database represent can be found here.
-
Install MariaDB. If you are having great difficulty installing MariaDB on your system, you can try Installing and Using MariaDB via Docker
-
Log in to MariaDB in a terminal.
-
Create a database.
CREATE DATABASE {database_name};- Replace
{database_name}with any name of your choosing.
- Replace
-
Log out of MariaDB.
-
Import the sql file into the database.
mariadb -u {username} -p {database_name} < tests/three_days_sample_data.sql- Replace
{username}with your MariaDB username. - Replace
{database_name}with the name of the database you created in step 3.
- Replace
-
Using the MariaDB CLI or a GUI tool such as HeidiSQL, verify that the database was created successfully and that the tables and data were imported correctly.
The app looks for a file called config.json containing launch options in the root folder of the repository.
config.json:
{
"user": "<your_username>",
"password": "<your_password>",
"host": "<your_host>",
"port": "<your_port>",
"database": "<your_database>",
"url_base_pathname": "<your_url_base_pathname>",
"query_row_limit": "<your_query_row_limit>",
"table_names_map": {
"game_info": "<your_game_info_table>",
"game_content_info": "<your_game_content_info_table>",
"game_player_info": "<your_game_player_info_table>"
}
}*The url_base_pathname must start and end with "/". This field is optional and defaults to "/" when undeclared.
*query_row_limit is an integer that sets the maximum number of games that a user will be allowed to query from the Query Page. A popup will inform the user if their query size is too large and exceeds the limit.
*It's better for port to be an integer instead of a string with quotes so that if you run pytest, the tests will be able to connect to the database.
*This file is not tracked in Git.
You can also use environment variables in place of config.json, as specified in the next section.
Environment variables instead of db_config.json may optionally be used for the database credentials.
The following environment variables must be set:
| Variable | Description |
|---|---|
DB_HOST |
The host of the database server. |
DB_PORT |
The port of the database server. |
DB_USER |
The username to use to connect to the database. |
DB_PASSWORD |
The password to use to connect to the database. |
DB_DATABASE |
The name of the database to connect to. |
It is up to you to determine how to set these environment variables. One example is provided below.
Visual Studio Code can be configured to set environment variables when opening any terminal in the editor. This is done by adding the environment variables to the .vscode/settings.json file.
{
"terminal.integrated.env.windows": {
"DB_USER": "root",
"DB_PASSWORD": "somepassword",
"DB_HOST": "127.0.0.1",
"DB_PORT": "3306",
"DB_DATABASE": "wesnoth_mp_database"
},
}For linux and macOS, terminal.integrated.env.linux and terminal.integrated.env.osx are also available.
Run the app using
python app.pyThe app will be served at port 8050 of your local host. You can view the app in a browser.
See footer_technology_stack.md for a list of the technologies used in this app.
Developer Notes:
- React is also involved, because Plotly uses it for their UI components. You don't need to know React unless you want to actually make your own Plotly components or start modifying existing ones. Sometimes, the JavaScript console of the browser will contain error messages that you won't otherwise see in your main terminal.
- Flask is also involved, because Dash apps are actually Flask apps, but you're not really meant to tinker with most of the Flask parts unless you are planning to do something outside of Plotly Dash coding conventions.
The Callback Graph makes it easy to track app state, app data, callback function call counts, and callback function execution time. Additionally, we get to see the order in which the callbacks are executed and their respective triggers.
The tests/ directory contains tests for the app. The tests are written using pytest. To run the tests, use
The port in config.json should be an integer and not a string with quotes for the tests to be able to connect to the database.
For example: 3306 instead of "3306"
pytestThe following pytest plugins are used:
| Package | Description |
|---|---|
| pytest-mock | Provides a mocker fixture that is used to mock functions and classes. |
| pytest-cov | (Optional Use). Generates coverage reports. |
| pytest-env | (Optional Use). If you are not using the .json files for app configuration, you need to use this to set environment variables during test. The same variables that you set in order to run the app can also be used for testing. See the pytest readme on how to use this. The pytest.ini file is in the .gitignore list. |
Install production dependencies using
pip install -r requirements/production.txtTo serve this app to end users, it is recommended to use a WSGI server such as Gunicorn or Waitress. The requirements/production.txt file already specifies Gunicorn, but this can be changed depending on the specific needs of the deployment.
With Gunicorn, the app can be served using the following command:
gunicorn --bind 0.0.0.0:$PORT app:serverThe command indicates that the server variable in the app.py file is the WSGI entry point. $PORT specifies the port number.