Backend Getting Started

Prerequisites

Python

• Install Python 3.13 on your machine.

Poetry

• Install Poetry on your machine.
• Make sure it is available on your PATH.

Configuration (.env file)

Both for local execution and local development, you need to specify some configuration arguments.

You can use the following .env file to get started:

POSTGRES_PASSWORD=abc123
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_DB=data-product-portal
POSTGRES_SERVER=localhost

CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5050,http://localhost:8080
AWS_DEFAULT_REGION=eu-west-1
LOGGING_DIRECTORY=./tmp/logs
HOST=http://localhost:3000/
SLOW_QUERY_LOGGING_ENABLED=True
OPENTELEMETRY_TRACES_ENABLED=True

Running the project

Installation

In order to install all project dependencies using poetry, open the 'backend' directory as a workspace in your favorite IDE and execute the command below.

poetry install

Starting required services

Required services can be started using docker compose:

docker compose up -d postgresql mailhog jaeger

Populating the database

In order to initialize your database with the correct structure, execute the command below from the backend folder.

poetry run python -m app.db_tool init "sample_data.sql"

This populates the database with sample data from sample_data.sql . If you want to use your custom data, you should create a .sql file similar to the sample_data.sql file and reference that one in the command above.

Running the backend

In order to run the project in development mode, after initializing the database, execute the command below.

poetry run python -m app.local_startup

🎉

The backend is now running on port 5050.

Enabling the MCP server

The MCP server can work (locally or remotely) via Claude Desktop. Install Claude Desktop and run poetry run fastmcp install claude-desktop app/remote_proxy.py -e $(pwd) --env-file ./.env --env DISABLED_AWS='true' in the backend folder. Make sure the HOST in your .env file is either referring to your localhost backend or the remote deployed backend.

Development utilities

Including the virtual environment in your IDE

• Execute the command below to display the location of your virtual environment.

poetry env info --path

• You can use this location to pass in your IDE to be able to run the source code from your IDE and to resolve all imports.

Data

A small CLI tool is delivered to enable database setup / migrations. The CLI tool fetches database configuration from the .env file in the current folder. Make sure your database connection variables are set up correctly. Execute python -m app.db_tool --help from the backend folder to receive the help text from this tool.

Force Database recreation

If you want to completely destroy and recreate the database when performing the commands listed below, you should specify the '--force' option.

python -m app.db_tool init --force "sample_data.sql"

Database migrations

Whenever you develop functionality that would include a database structure change, you will need to create an alembic migration script for it. This comes down to running python -m app.db_tool revision "{your message}" in the /backend directory.

In order to apply this migration using the database CLI tool you need to execute the command below.

python -m app.db_tool migrate

Testing

Integration testing

To run the integration tests, execute the following commands:

poetry install --all-groups
docker compose up -d postgresql
poetry run pytest -v

It will install test dependencies, boot up the test database and run the tests.

Load testing (Locust)

Run a baseline headless test against local backend (10 users, spawn 5/s, 1m):

poetry run poe loadtest --headless -H http://localhost:5050 -u 10 -r 5 -t 1m

For more info see backend/loadtest/locustfile.py