Koulu

A community platform with feed, classroom, calendar, members, and leaderboards.

Development

Prerequisites

• Python 3.12+
• Node.js 18+
• Docker and Docker Compose (v2)

Quick Start

The easiest way to get everything running:

./start.sh

This will check prerequisites, start Docker containers, install dependencies, run migrations, and set up your .env with the correct ports.

Per-Project Isolation

Each copy of this repo (or worktree) gets its own isolated Docker stack (containers, volumes, networks, ports) so multiple features can be developed simultaneously without interference.

How it works:

• scripts/project-env.sh computes a deterministic port offset from the project's absolute path
• KOULU_VOLUME_PREFIX (derived from directory name) gives each worktree unique Docker container/volume/network names
• The .env file is patched with the correct ports on each ./setup.sh run
• Every script header displays a banner with project name, branch, path, and ports

To see what ports your copy will use:

source scripts/project-env.sh
print_worktree_banner

Git Worktrees (Parallel Epic Development)

Use git worktrees to work on multiple epics simultaneously. Each worktree gets fully independent infrastructure.

Hierarchy: Epic (worktree) → Feature branches (within worktree) → main (deploy)

# Create a worktree for an epic (creates epic/leaderboards branch)
./scripts/worktree-create.sh leaderboards

# See all worktrees and their status (branch, ports, Docker state)
./scripts/worktree-status.sh

# Work in the new worktree
cd ../koulu-leaderboards
./start.sh          # Start dev servers (unique ports)

# Create feature branches within the epic worktree
git checkout -b feature/leaderboard-api
# ... implement, verify, commit ...
git checkout epic/leaderboards && git merge feature/leaderboard-api

git checkout -b feature/leaderboard-ui
# ... implement, verify, commit ...
git checkout epic/leaderboards && git merge feature/leaderboard-ui

# When the whole epic is complete, merge to main and deploy
git checkout main && git merge epic/leaderboards
git push origin main

# Tear down (stops Docker, removes volumes, removes worktree)
cd ../koulu
./scripts/worktree-teardown.sh leaderboards

What each worktree gets:

• Own Docker containers (postgres, redis, mailhog) with unique names
• Own Docker volumes (database data persists per worktree)
• Own host ports (deterministic, no collisions)
• Own .env and frontend/.env (generated by setup.sh)
• Own node_modules/ (per-worktree npm install)
• Own test databases (named per project)
• Shared Python virtualenv via pyenv (koulu)

Alembic migrations: Each worktree runs against its own database, so no runtime conflicts. When merging epic branches that both added migrations, resolve with alembic merge heads -m "merge".

Manual Setup

If you prefer to set things up step by step:

1. Source the project environment (sets COMPOSE_PROJECT_NAME and port variables):

   source scripts/project-env.sh

2. Start infrastructure services:

   docker compose up -d

3. Install Python dependencies:

   pip install -e ".[dev]"

4. Run database migrations:

   alembic upgrade head

5. Install frontend dependencies:

   cd frontend && npm install

Running

Use ./start.sh (recommended — starts both with correct ports). Or manually:

• Backend: source scripts/project-env.sh && uvicorn src.main:app --reload --host 0.0.0.0 --port ${KOULU_BACKEND_PORT}
• Frontend: cd frontend && npm run dev -- --port ${KOULU_FRONTEND_PORT}

Testing

• Backend: ./scripts/verify.sh
• Frontend: ./scripts/verify-frontend.sh
• E2E: ./scripts/run-e2e-tests.sh

Stopping

source scripts/project-env.sh
docker compose down

Add -v to also remove volumes (database data):

docker compose down -v