Skip to main content
This page covers the current local development runtime in blueaccademy. The docs repository itself does not run the app. It only serves this Mintlify site. The preferred first step is now Install Rancher Desktop. If you are contributing code, the second step is Install developer tooling.

​
Prerequisites

Make sure you have:
  • Rancher Desktop installed
  • Rancher Desktop running
  • Kubernetes enabled in Rancher Desktop
  • uv installed
  • Python 3.11+ available to uv
  • repo dependencies synced with uv sync --dev
  • Git hooks installed with uv run pre-commit install
  • A clone of blueaccademy

​
Setup

1

Start Rancher Desktop first

Launch Rancher Desktop and wait for it to finish initialization before you start the BlueAccademy stack.
2

Prepare the contributor toolchain

From ~/blueaccademy, run:
3

Open the product repo

Move into the main repo:
4

Start the stack

Build and start the services:
5

Wait for health and seed completion

On startup, the backend runs python -m backend.app.db.seed as a post-start command. That seed step loads starter content from backend/app/db/learning_content/.
6

Open the app

Open:
Use the flashcards slice from there.

​
Architecture overview

The current local stack runs three services: The Compose file waits for Postgres health before starting the backend and waits for backend health before starting the frontend.

​
Environment variables

The current Compose file sets these key variables: Current defaults:
The default Compose setup is for local development only.

​
Useful contributor commands

From ~/blueaccademy, these are the preferred commands to know:
  • cd infra && docker compose up --build: preferred local runtime for Postgres, backend API, and frontend
  • docker build -t blueaccademy-api:test . -f infra/api.Dockerfile: build backend image manually
  • docker build -t blueaccademy-frontend:test . -f infra/frontend.Dockerfile: build frontend image manually
  • cd frontend && npm run dev: run Vite locally without Docker
  • cd frontend && npm run build: build the frontend bundle
  • uv run python -m backend.app.db.seed: seed backend data locally

​
Seeds

Repo-managed starter content lives in:
  • backend/app/db/learning_content/cards.json
  • backend/app/db/learning_content/terminal-exercises.json
  • backend/app/db/learning_content/ckad-exercises.json
  • backend/app/db/learning_content/real-env-exercises.json

​
Stopping and restarting

To stop the stack:
Data persists because Postgres writes to ~/postgres/blueaccademy on the host.

​
Resetting to a clean state

If you want a clean database:
Then start the stack again. The next boot re-runs the seed step.

​
What not to assume

Local runtime availability does not imply public support for every route or page in the codebase.
  • The flashcards slice is the supported workflow today.
  • Guided terminal exercises are in progress.
  • CKAD simulations, broader real-environment labs, chat, and hosted sandbox orchestration are not yet documented as supported.

​
If Rancher Desktop is your first Kubernetes runtime

Verify these before debugging BlueAccademy itself:
If those commands do not work yet, fix your Rancher Desktop installation first.