core-api

The Core API for Prebunking at Scale.

The API is powered by litestar. The documentation is great - I'd suggest reading it before getting too stuck into the code.

Running the local development version

The easiest way to get started is using Docker to run a postgres instance.

You can bring up postgres using:

docker compose up pas-postgres -d

Once started, you'll need to create an .env file with the following contents:

API_KEYS='["abc123"]'
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=pas
DATABASE_PASSWORD=s3cret
DATABASE_NAME=pas

These values should match those in compose.yaml.

You'll need uv installed to start the actual API. Follow instructions to do this here.

Once uv is installed, you can install the various Python packages with:

uv sync

and start the development server with

 litestar --app core.app:app run --reload

Migrations

Migrations files should be placed in the core/migrations directory, following the naming format: {version}.{description}.{direction}.sql where version is an integer defining the order that migrations should be performed, description is a short description of the migration, and direction is either up or down indicating the migration direction. Examples:

• 1.create_users_table.up.sql
• 1.drop_users_table.down.sql
• 2.add_email_to_users.up.sql
• 2.remove_email_from_users.down.sql

It is recommended that migrations are wrapped in a transaction (e.g BEGIN; and COMMIT; statements), so that if a migration fails, the database state is not left in an inconsistent state.

Once a migration is ready, update MIGRATION_TARGET_VERSION in core/app.py to match the version you want the database to be at, and it will automatically apply when next run.

Deploying

Builds automatically happen whenever new code is pushed to the main or dev branches, and a new release is made.

Once a build has completed (check Actions on GitHub to verify), you'll need to update the image version.

To do this, cd deployment/dev or cd deployment/prod depending on where you want to update, and change the image: line so that the version matches the release you want to deploy e.g.:

image: europe-west4-docker.pkg.dev/pas-shared/pas/core-api:v0.5.0

To deploy the change, run the login script to make sure you are authenticated against the correct cluster (dev or prod), and use kubectl to apply the change:

./login.sh
kubectl apply -f deployment.yaml