Rocky

Prerequisites

• Python 3.11 or newer
• Node.js 20 or newer
• npm

First-time setup

1. Create a Python virtual environment

From the repository root in PowerShell:

py -3 -m venv .venv

If you need a different Python executable, use the full path with &.

2. Activate the virtual environment

.\.venv\Scripts\Activate.ps1

If PowerShell blocks activation, run once:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Install backend dependencies

pip install -r rocky-backend\requirements.txt

4. Install frontend dependencies

Push-Location rocky-interface
npm install
Pop-Location

5. Create environment files

Copy the examples and edit them for your environment:

• rocky-backend/.env.example -> rocky-backend/.env
• rocky-interface/.env.example -> rocky-interface/.env

For production, set ROCKY_DB_BACKEND=mongodb and provide ROCKY_MONGODB_URI.

Minimum required variables

Development minimum:

• rocky-backend/.env: ROCKY_APP_ENV=development, ROCKY_DB_BACKEND=mongita, ROCKY_API_HOST, ROCKY_API_PORT
• rocky-interface/.env: PUBLIC_APP_ENV=development, PUBLIC_API_BASE_URL, PUBLIC_ENABLE_MICROSOFT_OAUTH, ROCKY_WEB_HOST, ROCKY_WEB_PORT, ROCKY_ALLOWED_HOSTS

For development Microsoft OAuth, set:

• rocky-interface/.env: PUBLIC_ENABLE_MICROSOFT_OAUTH=true, PUBLIC_MICROSOFT_CLIENT_ID, optional PUBLIC_MICROSOFT_TENANT_ID, optional PUBLIC_MICROSOFT_REDIRECT_URI
• rocky-backend/.env: ROCKY_ENABLE_MICROSOFT_OAUTH=true

Production minimum:

• rocky-backend/.env: ROCKY_APP_ENV=production, ROCKY_DB_BACKEND=mongodb, ROCKY_MONGODB_URI, ROCKY_ENABLE_DB_INSPECTOR=false, ROCKY_API_HOST, ROCKY_API_PORT
• rocky-interface/.env: PUBLIC_APP_ENV=production, PUBLIC_API_BASE_URL, PUBLIC_MICROSOFT_CLIENT_ID, optional PUBLIC_MICROSOFT_TENANT_ID, optional PUBLIC_MICROSOFT_REDIRECT_URI, ROCKY_WEB_HOST, ROCKY_WEB_PORT, ROCKY_ALLOWED_HOSTS

Auth mode behavior:

• Development: preview auth by default; Microsoft OAuth enabled only when override env variables are true.
• Testing: preview auth only.
• Production: Microsoft OAuth only.

Both launchers load .env and .env.local from the repo root, backend, and frontend directories.

Running locally

Development

Run both backend and frontend together:

python run-dev.py --mode both

Other modes:

• python run-dev.py --mode backend
• python run-dev.py --mode frontend

Production preview

Build the frontend, start the backend in production mode, and launch the frontend preview server:

python run-production.py

Backend-only production mode:

python run-production.py --mode backend

Backend

Backend runs on http://127.0.0.1:5001 by default.

Useful endpoints:

• GET /health
• GET /users
• GET /courses
• GET /analytics/kpis
• GET /widgets/default
• GET /help/faq

Admin-only endpoints require the admin headers passed by the Svelte proxy layer.

Seed data

Backend-owned fixtures live in:

• rocky-backend/seed-data/account/users.json
• rocky-backend/seed-data/courses/courses.json
• rocky-backend/seed-data/analytics/kpis.json
• rocky-backend/seed-data/analytics/activity.json
• rocky-backend/seed-data/widgets/widgets.json
• rocky-backend/seed-data/help/faq.json

Seed the backend database with:

python rocky-backend\seed_from_backend.py

Tests

Backend unit tests:

python -m unittest discover -s run-test/backend -p "test_*.py" -v

Frontend browser tests depend on a running browser and Chromium/WebDriver setup:

python -m unittest discover -s run-test/frontend -p "test_*.py" -v