Skip to content

Installation

AlgoStudio is two Python services over one Postgres database:

Service Stack Default port Job
app Flask 5000 (dev) / 5500 (compose) The web UI, sessions, GitHub OAuth
api FastAPI 8000 (dev) / 8800 (compose) Runs student code in Docker, serves the VS Code extension

Requirements

  • Python 3.14
  • PostgreSQL 17+
  • Docker — the api spins up a container per submission, so the Docker socket must be reachable from wherever the api runs
  • A GitHub OAuth app (create one) — login is GitHub-only right now

Environment

Copy AlgoStudio/src/.env.example to AlgoStudio/src/.env and fill it in:

Variable What
DB_KEY Postgres DSN fragment, user:password@host/database
FLASK_SECRET_KEY Session signing key — generate with python -c "import secrets; print(secrets.token_hex(32))"
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET From your GitHub OAuth app
GITHUB_REDIRECT <your app url>/auth/github/callback — must match the OAuth app setting
API_URL Where browsers reach the api (e.g. https://api.example.com)
RESOLVER_URL Where browsers submit code — usually the same as API_URL
ALLOWED_ORIGINS CORS allowlist for the api; defaults to * with a warning — set it in production
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASSWORD / SMTP_SECURITY / EMAIL_FROM Outgoing email. Leave SMTP_HOST unset and emails are logged instead of sent

Tables are created automatically on first start — no migration step.

Run it (development)

pip install -r AlgoStudio/src/api/requirements.txt
pip install -r AlgoStudio/src/app/requirements.txt

cd AlgoStudio/src
uvicorn api:app --env-file .env --reload    # api → :8000
flask run --port 5000 --debug               # app → :5000

Run it (docker-compose)

AlgoStudio/src/docker-compose.yml runs both services (app on :5500, api on :8800). It mounts the host's Docker socket into the api container so submissions can run, and python app/build_assets.py minifies the static assets on boot. Bring your own Postgres and point DB_KEY at it.

cd AlgoStudio/src
docker compose up

Bootstrap the first admin

  1. Log in once through GitHub so your user row exists.
  2. Flip the admin flag in the database:
UPDATE users SET admin = true WHERE email = 'you@example.com';

From here everything is in-app: the Admin link appears in the header, and the AI assistant can build your first course. This SQL statement is the only time you need to touch the database.

Fresh accounts have no access

Users who log in before being added to a group (or made maintainer/admin) see a holding page. That's deliberate — see the access model.