See also: Helper.md — concise build & test commands you can copy-paste.

This guide walks through preparing a Windows 11 workstation to build, run, and operate the Banking System project entirely from scratch. Follow the steps in order; each section builds on the previous one.

• Windows 11 (21H2 or later) with administrator privileges.
• Reliable internet connection for downloading tooling and dependencies.
• At least 4 GB of free disk space.

💡 All command snippets assume PowerShell running as an administrator unless stated otherwise.

winget install --id Git.Git -e --source winget

Confirm installation:

git --version

The project targets Java 17. Install the Temurin distribution via Windows Package Manager:

winget install --id EclipseAdoptium.Temurin.17.JDK -e --source winget

Verify:

java -version
javac -version

winget install --id curl.curl -e --source winget

1. Install via the Windows Package Manager:

   winget install --id Oracle.MySQL -e --source winget

   If the command prompts to open the MySQL Installer UI, complete the wizard using the Developer Default configuration.
2. Configure the root password when prompted. Record it securely.
3. Ensure MySQL is running as a Windows service (the installer does this by default).
4. Open a MySQL shell and create an application database and user for the banking service:

   "CREATE DATABASE banking CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" | mysql -u root -p
   "CREATE USER 'bank_user'@'localhost' IDENTIFIED BY 'ChangeMe123!';" | mysql -u root -p
   "GRANT ALL PRIVILEGES ON banking.* TO 'bank_user'@'localhost';" | mysql -u root -p
   "FLUSH PRIVILEGES;" | mysql -u root -p

   ℹ️ Passwords shown here are examples; choose unique credentials for your environment. The application connects to this schema beginning with the current release.

Choose a directory (e.g., C:\dev) and run:

cd C:\dev
git clone https://github.com/<your-org>/Banking-System.git
cd Banking-System

If your organization uses Git over HTTPS with personal access tokens, replace <your-org> and provide credentials when prompted.

Configure the runtime to use the MySQL instance created earlier:

$env:BANKING_STORAGE_MODE = "jdbc"
$env:BANKING_JDBC_URL = "jdbc:mysql://localhost:3306/banking?useSSL=true&requireSSL=false&serverTimezone=UTC"
$env:BANKING_DB_USER = "bank_user"
$env:BANKING_DB_PASSWORD = "ChangeMe123!"
[Environment]::SetEnvironmentVariable("BANKING_STORAGE_MODE", $env:BANKING_STORAGE_MODE, "User")
[Environment]::SetEnvironmentVariable("BANKING_JDBC_URL", $env:BANKING_JDBC_URL, "User")
[Environment]::SetEnvironmentVariable("BANKING_DB_USER", $env:BANKING_DB_USER, "User")
[Environment]::SetEnvironmentVariable("BANKING_DB_PASSWORD", $env:BANKING_DB_PASSWORD, "User")

Persisting these values ensures new PowerShell sessions inherit the configuration. If you need to test the legacy snapshot flow, unset BANKING_STORAGE_MODE and set BANKING_DATA_PATH instead.

From the repository root:

New-Item -ItemType Directory -Force -Path build\classes | Out-Null
Get-ChildItem -Path src -Filter *.java -Recurse | ForEach-Object { $_.FullName } | Out-File -Encoding ascii sources.txt
javac -d build\classes @sources.txt

✅ Compilation should finish without errors and populate build\classes with .class files.

The migration helper executes JDBC migrations so the schema matches the application version and records progress in bank_schema_migrations.

bash deploy\scripts\run-migrations.sh

• If prompted about executing scripts, allow PowerShell to run the bundled Bash via Git.
• The script reads BANKING_JDBC_URL, BANKING_DB_USER, and BANKING_DB_PASSWORD; verify they are set before running.

java -cp build\classes banking.BankingApplication

• Follow the on-screen menu to open accounts, post transactions, and exit cleanly (option 7) so state is saved.

Start the HTTP server in a new PowerShell window:

java -cp build\classes banking.api.ApiApplication

Request a short-lived operator token and interact with the API from another window (every request must include the bearer token header):

$env:BANKING_TOKEN = (curl -Method Post -Body "username=admin&password=admin123!" http://localhost:8080/auth/login | ConvertFrom-Json).token
curl -H "Authorization: Bearer $env:BANKING_TOKEN" -X POST "http://localhost:8080/accounts" -d "name=Grace&type=savings&deposit=1000"
curl -H "Authorization: Bearer $env:BANKING_TOKEN" "http://localhost:8080/accounts"
curl -H "Authorization: Bearer $env:BANKING_TOKEN" "http://localhost:8080/accounts/<ACCOUNT_NUMBER>"
curl -H "Authorization: Bearer $env:BANKING_TOKEN" -X PUT "http://localhost:8080/accounts/<ACCOUNT_NUMBER>" -d "userName=Grace%20Hopper"
curl -H "Authorization: Bearer $env:BANKING_TOKEN" -X DELETE "http://localhost:8080/accounts/<ACCOUNT_NUMBER>"
curl -H "Authorization: Bearer $env:BANKING_TOKEN" "http://localhost:8080/metrics"

Use Ctrl+C in the API window to trigger a graceful shutdown and final persistence cycle once testing completes.

If you plan to test containerized workflows:

1. Install Docker Desktop for Windows and enable WSL 2 integration.
2. Build images locally:

   docker compose -f deploy\compose\docker-compose.yml build

3. Run the stack:

   docker compose -f deploy\compose\docker-compose.yml up

4. Tear down with docker compose ... down when finished.

• javac not found: Re-open PowerShell after installing the JDK so the PATH updates, or add %ProgramFiles%\Eclipse Adoptium\jdk-17\bin manually.
• bash command missing: Ensure Git for Windows installed its bundled GNU tools; re-run the installer and enable the “Git Bash utilities” option if necessary.
• MySQL authentication errors: Reset the root password via the MySQL Installer or run mysqladmin -u root password <newPassword>, then update BANKING_DB_PASSWORD to match.
• Port conflicts on 8080: Stop other services (like IIS Express) or update ApiApplication.HTTP_PORT before starting the API server.

You now have a fully configured Windows 11 environment capable of building, testing, and operating the Banking System locally.