Quick start

TestLookup collects the results of your automated software tests. This guide gives you two ways to start it, then shows you how to sign in and send your first test report:

• Option A, the one-command install, runs the published images. Use it to try TestLookup or to run it on one server.
• Option B, the clone, builds TestLookup from its source code with demo data. Use it for development.

Choose one. Both use the same ports and container names, so only one copy of TestLookup can run on a machine.

Prerequisites

Both options need:

• Docker with Compose v2, and Bash. To check your Docker version, run docker compose version.
• About 8 GB of free memory for the core services. Local AI models need more.
• These free ports: 3000, 8000, 8002, 5433, 6379, 9000 and 27017.

Option A also needs curl or wget.

Option B also needs Git and GNU Make. Its step that uploads the sample reports runs curl and python3 on your machine. If either one is missing, TestLookup still starts, but the sample uploads fail without showing an error.

On Windows, run every command on this page from Git Bash or WSL, because the installer and the Makefile use Bash.

Option A: one-command install

Option A. To run TestLookup from its published images without cloning the repository, run:

curl -fsSL https://raw.githubusercontent.com/test-intelligence/testlookup/main/install.sh | bash

The installer does three things:

1. It downloads the release Compose file, docker-compose.release.yml, into a folder named testlookup.
2. It writes a .env settings file for production mode, with random passwords and keys.
3. It downloads the images from ghcr.io/test-intelligence/testlookup and starts them. Nothing is built from source, and the first start downloads a few GB.

When it finishes, it prints the admin password once. The password is also saved in .env as INITIAL_ADMIN_PASSWORD, and you choose a new one when you first sign in. Allow a minute or two for the database updates and health checks. Then open the dashboard at http://localhost:3000.

You can set options in front of bash. For example, this command adds demo projects with sample data:

curl -fsSL https://raw.githubusercontent.com/test-intelligence/testlookup/main/install.sh | TL_PROFILE=demo bash

The installer reads these options:

• Extra services: set TL_PROFILE=demo to add demo projects with sample data, or TL_PROFILE=local-llm to add the local AI model services.
• Image version: set TESTLOOKUP_VERSION to choose the image tag. The default is latest, which follows the newest build of the main branch. No release has been tagged yet.
• Install folder: set TL_DIR to change the folder. The default is ./testlookup.
• Installer files: set TL_REF to choose the branch, tag or commit the installer downloads its files from. The default is main.
• Prepare only: set TL_NO_UP=1 to download the files and write .env without starting anything.

If your company policy asks you to, read the script before you pipe it to a shell. Once Option A is running, go to Addresses to open. Do not also run Option B.

Option B: build from a clone

Option B builds TestLookup from its source code, for development. Use it instead of Option A, not as well.

git clone https://github.com/test-intelligence/testlookup.git
cd testlookup

If TestLookup is already running from another clone, or from Option A, stop it first. The container names, ports, networks and storage volumes are fixed. So only one copy can run on a machine, unless you write a full Compose override file that changes all of them.

Start with make quickstart

make quickstart

This one command does four things:

1. It creates a development .env settings file, but only if you do not have one yet.
2. It builds and starts the core services.
3. It waits until the API answers its readiness check, /health/ready.
4. It uploads the sample JUnit reports from samples/junit/, while a separate task loads the demo projects.

The first build downloads images and libraries, so allow several minutes. To start without the demo uploads, use make dev. To add the local AI model services, use make dev-llm. The generated settings suit a local test machine only, so review them before you use them anywhere else.

Option B commands

Here is the whole Option B sequence, run from a fresh clone. The last two commands show what started and the most recent log lines:

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

If there is no .env file yet, Make creates one with scripts/gen-dev-env.sh. The file gets random local passwords and database addresses that match them. Check that git status does not list .env, so it never reaches your repository. With make dev-llm, Make also downloads the local AI models that TestLookup is set up to use.

The task that loads the demo data runs on its own and can finish after the containers start. For details, see the Makefile, the example settings file and the deployment options.

Addresses to open

Both options serve these addresses:

• The dashboard: http://localhost:3000
• The user guide inside the app: http://localhost:3000/docs
• The interactive API reference (Swagger): http://localhost:8000/api-docs
• The MCP server, which lets AI assistants such as Claude or Cursor use TestLookup: http://localhost:8002/sse

Check that the API is ready:

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

A ready API and running containers do not prove that the background workers are processing jobs. The surest check is a first report that becomes a finished run, as described in First report. With Option B, make smoke also checks the API, the web app and the demo data.

First report

1. Sign in at http://localhost:3000.

   • Option A: sign in as admin with the password the installer printed, then choose a new password.
   • Option B: the login page shows a quick-login panel. Choose Admin. No password is needed. See Development-only login.

2. Pick a project from the project selector in the header. Option B already has demo projects, and so does Option A with TL_PROFILE=demo. Otherwise, create a project:

   • Open Settings › Project › Projects (http://localhost:3000/projects) and choose New Project.
   • Give it a name and a slug, the short name used in links. You cannot change the slug later.

3. Send a report. Use a JUnit XML file that your tests already write, the samples in samples/junit/ of the Option B clone, or the two-test file in the first report tutorial.

   • In the web app: open Runs, choose Upload report, then pick the project, the file and a build label. If you cannot see the button, an administrator needs to turn on the manual_upload setting under Settings › System › Feature flags.
   • From a terminal: create an API key under Settings › Account › My API keys (http://localhost:3000/settings/my-api-keys). TestLookup shows the key only once. Then list your projects, copy the project ID and upload the file:

   export TL_URL='http://localhost:8000'
   export TL_API_KEY='paste-your-key-here'
   curl --fail-with-body "$TL_URL/api/v1/projects" -H "X-API-Key: $TL_API_KEY"
   
   export TL_PROJECT='paste-the-project-id-here'
   curl --fail-with-body "$TL_URL/api/v1/ingest/file" \
     -H "X-API-Key: $TL_API_KEY" \
     -F "project_id=$TL_PROJECT" -F 'build_number=first-1' \
     -F 'format=auto' -F 'file=@results.xml'

4. Check the result. TestLookup first accepts the report and queues it (HTTP 202), so the run is not finished yet. The response contains a run_id and a task_id. Check the task until its status reads succeeded. The run then appears under Runs.

   export TL_TASK_ID='paste-the-task_id-here'
   curl --fail-with-body "$TL_URL/api/v1/ingest/uploads/$TL_TASK_ID" -H "X-API-Key: $TL_API_KEY"

   The upload form in the web app shows the same progress for about 60 seconds.

The first report tutorial continues with a worked example and the common errors.

Development-only login

The quick-login panel is a development feature. It works only when APP_ENV=development and DEV_AUTO_LOGIN_ENABLED=true. The .env file that Option B creates sets both. In production, TestLookup refuses to start with quick login turned on. Never copy these settings, or that .env file, to a staging or production server.

The one-command install runs in production mode and has no quick login. Sign in as admin with the password the installer printed.

Some accounts use two-step sign-in (MFA). For those accounts, a successful sign-in asks for the code instead of starting a session. A script that signs in must check for that case.

On Windows

Run every command on this page from Git Bash or WSL, not PowerShell. That includes the installer and make. The installer and the Makefile use Bash, and the Option B sample upload also needs python3 in that shell.

Troubleshooting

If something did not start, check the containers and the logs of the backend, worker, scheduler (beat) and demo-data (seed) services. The demo-data task can finish after the containers start.

For Option A, run these from the testlookup folder:

docker compose -f docker-compose.release.yml ps
docker compose -f docker-compose.release.yml logs -f
docker compose -f docker-compose.release.yml down   # stops TestLookup and keeps its data

For Option B, run these from the clone:

docker compose ps
docker compose logs --tail=100 backend worker beat seed-init
make stop   # stops TestLookup and keeps its data

To start again from nothing, run make clean CONFIRM=yes. It deletes every data volume, so use it only when you mean to.