> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blueaccademy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run BlueAccademy locally

> Detailed local setup instructions for the current BlueAccademy runtime in the main product repository, starting with Rancher Desktop.

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](/installation/rancher-desktop).
If you are contributing code, the second step is [Install developer tooling](/installation/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

<Steps>
  <Step title="Start Rancher Desktop first">
    Launch Rancher Desktop and wait for it to finish initialization before you start the BlueAccademy stack.
  </Step>

  <Step title="Prepare the contributor toolchain">
    From `~/blueaccademy`, run:

    ```bash theme={null}
    uv sync --dev
    uv run pre-commit install
    ```
  </Step>

  <Step title="Open the product repo">
    Move into the main repo:

    ```bash theme={null}
    cd ~/blueaccademy
    ```
  </Step>

  <Step title="Start the stack">
    Build and start the services:

    ```bash theme={null}
    docker compose -f infra/docker-compose.yml up --build
    ```
  </Step>

  <Step title="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/`.
  </Step>

  <Step title="Open the app">
    Open:

    ```
    http://localhost:5173
    ```

    Use the flashcards slice from there.
  </Step>
</Steps>

## Architecture overview

The current local stack runs three services:

| Service       | Port   | Role                                                            |
| ------------- | ------ | --------------------------------------------------------------- |
| `postgres-db` | `5432` | Persistent storage for decks, cards, settings, and review state |
| `backend-api` | `8000` | FastAPI application for the current supported flashcard slice   |
| `frontend`    | `5173` | Frontend application you open in the browser                    |

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:

| Variable                   | Description                              |
| -------------------------- | ---------------------------------------- |
| `DATABASE_URL`             | Backend connection string for Postgres   |
| `VITE_PYTHON_API_BASE_URL` | Frontend base URL for the Python backend |

Current defaults:

```bash theme={null}
DATABASE_URL=postgresql+psycopg://blueaccademy:mypassword@host.docker.internal:5432/blueaccademy
VITE_PYTHON_API_BASE_URL=http://localhost:8000
```

<Warning>
  The default Compose setup is for local development only.
</Warning>

## 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:

```bash theme={null}
docker compose -f infra/docker-compose.yml down
```

Data persists because Postgres writes to `~/postgres/blueaccademy` on the host.

## Resetting to a clean state

If you want a clean database:

```bash theme={null}
docker compose -f infra/docker-compose.yml down -v
```

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:

```bash theme={null}
kubectl version --client
helm version
```

If those commands do not work yet, fix your Rancher Desktop installation first.