Built With

• Flask - Python Based Web Framework Used
• Jinja2 - HTML Templating Language for Python
• Peewee - A small, expressive ORM used for database communications
• MySQL - SQL database engine

Requirements

• python 3.11+
• linux, unix, mac, windows (with WSL)
• git

Note: The setup steps below were written for the environment of the contributor who wrote them. If you are setting up on macOS, Windows, or Docker and run into OS-specific differences, please note them here.

Setting Up a Linux Environment on Windows

1. Install WSL and Ubuntu

Open PowerShell as Administrator and check:

wsl --status
wsl -l -v

If WSL is not installed: wsl --install After it is completed run wsl -l -v to see if Ubuntu is installed. If Ubuntu is not installed run: wsl --install -d Ubuntu, then restart your laptop afterwards.

Then launch Ubuntu with: wsl.

2. Install MySQL

• Check whether MySQL is already installed in PowerShell: mysql --version .
• You can also check the MySQL installation directory: Get-ChildItem "C:\Program Files\MySQL" -ErrorAction SilentlyContinue .
• From WSL, you can check the Windows MySQL installation in bash with: ls "/mnt/c/Program Files/MySQL" .
• If MySQL GUI is not installed, download the MySQL Installer: https://dev.mysql.com/downloads/installer/
• You will see the prompt to log in or sign up instead choose “No thanks, just start my download.”
• During the installation process, you will be given the option to select client, server or both and you should choose both.

3. Install Python

From WSL/Ubuntu check if python is installed:

python3 --version
pip3 --version

If Python is not installed:

sudo apt update
sudo apt install python3 python3-pip python3-venv

After installation, verify it again: python3 --version

Afterwards, go to: Running BCSR after the setup section

Setting Up a Linux Environment on MacOS

1. Install Homebrew

Check whether Homebrew is installed:

brew --version

• If you receive: command not found: brew
• Install Homebrew by running the following command in Terminal: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
• Then verify: brew --version

2. Install MySQL

• Check whether MySQL is installed:

mysql --version
brew list | grep mysql

If MySQL is not installed go to the MySQL Community Server download page: https://dev.mysql.com/downloads/mysql/

Download the correct DMG:

• Apple Silicon: ARM64
• Intel Macs: x86_64

During setup, configure the MySQL root account. BCSR commonly uses:

• Username: root
• Password: root

If you use a different password, update app/secret_config.yaml.

Test the connection: mysql -u root -p

3. Install Python

Check you installed Python version and pip:

python3 --version
pip3 --version

If Python is not installed: brew install python

Setting Up on Linux

1. Install Python

Check your Python version:

python3 --version
pip3 --version

If Python is not installed (Debian/Ubuntu):

sudo apt update
sudo apt install python3 python3-pip python3-venv

2. Install MySQL

• Check whether MySQL is already installed: mysql --version
• If it is not installed (Debian/Ubuntu):

sudo apt install mysql-server
sudo service mysql start

• Test the connection: mysql -u root -p

Afterwards, go to: Running BCSR after the setup section

Running BCSR after the setup

Navigate to your BCSR repository e.g.: cd ~/Desktop/SSDT/bcsr

1. Activate the Virtual Environment

On Windows, first enter WSL:

wsl

Then, on either Windows/WSL or macOS, run:

source setup.sh

You should see (venv) at the beginning of your terminal prompt.

• During the setup, if you have this error: -bash: setup.sh: line <something>: syntax error: unexpected end of file from "if" command on line 19 go to the bottom of your IDE and find CRLF and click it to select LF

Note: In order for the application to work, you must activate the virtual environment.

Note: Also, If you ever want to deactivate the virtual environment for any reason just type deactivate into the terminal.

2. Verify Database Connection

2.1 Check MySQL is Running

For MacOS:

• Check MySQL is running: brew services list
• If MySQL is stopped: brew services start mysql

For Windows PowerShell (Administrator):

Note: For window users *mysql* finds all mysql and you will see

• Check MySQL is running: Get-Service mysql
• Example:

Status	Name	Display Name
Running	MySQL80	MySQL80
Stopped	MySQL84	MySQL84

• Start the required service with: Start-Service MySQL80 (Replace MySQL80 with your service name).

2.2 Test the MySQL Login

• Run: mysql -u root -p
• If your password is root: mysql -u root -proot
• A successful connection will show: mysql>

2.3 Check the BCSR Database

• Inside MySQL: SHOW DATABASES;
• If bcsr does not exist:

CREATE DATABASE bcsr; 
USE bcsr;

2.4 Check Permissions

Run:

SELECT USER(), CURRENT_USER(); 
SHOW GRANTS FOR CURRENT_USER;

If you see:

GRANT ALL PRIVILEGES ON `bcsr`.* TO `root`@`localhost`
or
GRANT ALL PRIVILEGES ON *.* TO `root`@`localhost`

then the user already has the required access.

If the access is missing, grant it with:

GRANT ALL PRIVILEGES ON bcsr.* TO 'root'@'localhost'; FLUSH PRIVILEGES;

2.5 Verify MySQL Authentication Method

Check which authentication plugin you are using:

SELECT user, host, plugin
FROM mysql.user
WHERE user = 'root';

You may see something like: root | localhost | caching_sha2_password

Modern MySQL commonly uses: caching_sha2_password.

If the root account needs to be reset to use SHA authentication and the correct password, run:

ALTER USER 'root'@'localhost'
IDENTIFIED WITH caching_sha2_password BY 'root';

Then refresh the privileges: FLUSH PRIVILEGES;

Verify again:

SELECT user, host, plugin FROM mysql.user WHERE user = 'root';

The result should show: root | localhost | caching_sha2_password

Then test the login again: mysql -u root -p

3. Create the Secret Config

The application reads its database credentials and secret key from app/secret_config.yaml, which is not tracked in Git. Create it from the example:

cp app/example_secret_config.yaml app/secret_config.yaml

Then edit app/secret_config.yaml and set secret_key to a value of your own, along with the MySQL db_name, host, username, and password for your local database.

Note: setup.sh tries to make this copy for you, but it looks for the example file in the wrong place, so copy it manually as shown above.

4. Create the Database Tables

Warning Make sure in your secret_config.yaml the password and username under db match your MySQL installation values.

Create the empty database first if it does not exist yet (see step 2.3), then build the tables:

python mysql_migration.py
or
python3 mysql_migration.py

Note: Do not use create_db.py for this. It is left over from when this project used SQLite and does not work against the current MySQL configuration.

5. View the Database

Connect to MySQL:

mysql -u root -proot

Once connected, you should see the MySQL prompt:

mysql> 

6. Run the Application

Start BCSR with:

python app.py
or
python3 app.py

The terminal will display a local URL. Open that URL in your browser to access the application.