Development setup

Get the code

Clone the official repository, or add a Git worktree, and create a branch for your change. Write down the commit you start from.

git clone https://github.com/test-intelligence/testlookup.git
cd testlookup
git switch -c your-name/focused-change

Read the development guide on GitHub before you start the services.

Run one copy at a time

A separate checkout keeps your code changes apart from other work. But the Compose files use fixed container names, ports, networks and volumes. So run one TestLookup copy at a time, unless you’ve written a Compose override for every one of them.

The services publish these ports on your machine:

Never point database migrations or cleanup commands at another contributor’s copy, or at a shared environment.

Tool prerequisites

For container-based development, you need Git, Docker with Compose v2, GNU Make and Bash. The Makefile uses Bash, so on Windows run it from Git Bash or WSL. The contribution guide asks for 8 GB of RAM for the core services, and 16 GB with the local AI model.

To run the backend and the web app directly on your machine instead, you also need Python 3.11 or newer. You need Node 20 or newer too, which is the contribution guide’s minimum for the web app. The development guide uses these commands, run from the repository root unless noted:

python -m venv .venv
source .venv/bin/activate              # PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r backend/requirements.txt
python -m pip install -e ./cli

cd frontend && npm ci && npm run dev    # in one terminal, from the repository root

cd backend                              # in a second terminal, from the repository root, with the venv active
alembic upgrade head
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

Vite, the web app’s development server, forwards API calls to your local backend. Full flows still need the databases, the message broker, file storage and the workers. So give the backend the addresses and secrets of services that you own.

Read scripts before you run them. Keep the .env settings file out of Git, and use throwaway local passwords and keys. The Makefile writes matching local secrets into .env only when that file doesn’t exist yet. If Bash isn’t available, it copies .env.example instead, and you must fill in the secrets yourself.

Core setup

To start the core services with demo data, run:

make quickstart

The command starts the core services and waits until the readiness check answers. It then uploads the sample JUnit reports from samples/junit/, while a setup task loads the demo projects. When it prints Demo ready!, open the dashboard and choose Admin in the quick-login panel on the sign-in page. You don’t need a password.

Quick login works only because the generated .env runs TestLookup in development mode. Never carry that setting beyond a throwaway machine.

If something looks wrong, check the containers and the recent logs:

docker compose ps
docker compose logs --tail=100 backend worker worker-children beat seed-init

There are other ways to start:

• To start the core services without the demo uploads, run make dev. It prints the local addresses, including the Flower monitor for Celery at port 5555. Flower uses the basic-auth username and password in .env. To follow the demo data loader on a first run, use make dev-logs-seed.
• For machines with less memory, make dev-lite starts a smaller set of services.
• To add the optional local AI services and download their models, run make dev-llm. See Configure local AI.

Database schema changes go through Alembic, which runs inside the backend container:

Run them only against your own throwaway copy. The Makefile on GitHub lists every command.

Check that it works

Running containers don’t prove that TestLookup works. Start with these two checks:

make smoke
curl -f http://localhost:8000/health/ready

The smoke test checks the running services. It ends with a non-zero exit code when a core check fails. The API’s health checks each answer a different question:

Next, check that the latest database migration and the component versions match. Then check that a worker reads every configured queue. In the development Compose file, two services read the queues:

A log or health check that leaves out worker-children never shows that queue. Before you call a change ready for release, send one report all the way through: saving, analysis, review and the final report.

Follow one report through the code

To learn the code, follow one report through it:

1. Read backend/app/bootstrap.py, where the API routers are mounted.
2. Find POST /api/v1/ingest in the API reference.
3. Follow the upload guide on GitHub from the upload to the finished run, and on to the follow-up work queued after it.
4. Find the run page in the frontend that shows the result.

Then send a small report to your own copy. Watch these happen as separate events: TestLookup accepting the upload, saving the run, running the analysis and setting the review state.

Make your first change a small change to how something looks, and run its focused frontend test. Do that before you touch storage, permissions, queues or state changes. The codebase map gives the full reading order, from API route to screen.

Cleanup

To shut down, run make stop. It stops the main services and the optional local AI services, and keeps the data volumes.

The clean command deletes data. It removes the named volumes for:

• PostgreSQL;
• MongoDB;
• the Valkey message broker, which runs as the redis service;
• the S3-compatible file store, which runs as the minio service;
• Ollama models;
• Chroma data.

make clean CONFIRM=yes

Use it only on a copy you mean to throw away. Back up any data you need before an upgrade, or before a cleanup like this.

Next: choose the tests and quality checks for your change.