CHRIS Backend

TODO

Installing Package Dependencies

You will need uv and bun installed to test this application.

• uv
• bun

Dev Setup

1. Copy .env.example to .env and chris-frontend/.env.example to chris-frontend/.env then modify the values within to use your configuration.

2. Run docker compose -f docker-compose-dev.yml up -d --build then go to localhost:8080. Log in with admin:admin.

3. Within Keycloak create a new realm with the chris-realm-export.json export. Click into the chris-realm Realm, and then click into Clients and go to chris-backend. Then regenerate the Client Secret and paste it into the chris-backend/.env file.

4. Next in Keycloak go into Identity Providers and paste your Discord client secret.

5. Keycloak is now fully configured. Run docker compose -f docker-compose-dev.yml up -d --build web api. to rebuild just the frontend and backend technically you only need to rebuild the api but it's good to know this command for development.

6. Load the latest migrations to the api docker compose exec api /migrate.sh upgrade

7. Your app should now be fully configured. Open localhost:5173 to get started.

Live Reloading

You can use docker compose down web && cd chris-frontend && bun run dev for live reloading on the frontend after successful application startup.

Managing the Application

• Python: uv run ruff format ./ && uv run isort --profile black ./ && uv run ruff check --fix ./

• Python Type Checking: uv run mypy chris/ --config-file pyproject.toml

• TypeScript: cd chris-frontend && bun run lint

Migrations

• turn off all running containers then start up only the api and db containers docker compose down -v docker compose up -d --build api db
• upgrade the database schema to latest docker compose exec api /migrate.sh upgrade
• creating a new migration run docker compose exec api /migrate.sh autogen "description"
  • after this step you will need to extract the migrations file generated manually from the docker container with docker compose exec api /bin/bash then navigate to chris/migrations/ and copy the file generated and bring it back to your local machine to be committed to the repository.
• modify the migration file locally and test it with docker compose exec api /migrate.sh upgrade
• once migration is successful, commit the migration file.
• docker compose exec api /migrate.sh upgrade is the standard method of deploying migrations in prod

Migration Script Reference

Command	Description
/migrate.sh upgrade	Apply all pending migrations
/migrate.sh current	Show current migration status
/migrate.sh autogen "Description"	Generate new migration (dev only)
/migrate.sh stamp head	Mark DB as current without running migrations