Skip to content

Backend setup

The backend is a set of services that the desktop app talks to. They run in Docker on your own computer, or on a shared lab machine. You start them all with one command.

1. Install Docker

Install Docker Desktop and start it. Wait until the whale icon in the menu bar or system tray says Docker is running.

In Docker Desktop → Settings → Resources, give Docker at least 6 GB of memory. 8 GB or more is better for large cubes.

Install Docker Engine and the Compose plugin by following the official guide for your distribution. Then let your user run Docker without sudo:

sudo usermod -aG docker $USER   # then log out and back in

Check that it works:

docker compose version

2. Download the compose file

Create a folder for QCLM and download the docker-compose.yml into it:

mkdir qclm-backend && cd qclm-backend
curl -fsSLO https://qclm.iabdinur.dev/install/docker-compose.yml

mkdir qclm-backend; cd qclm-backend
Invoke-WebRequest https://qclm.iabdinur.dev/install/docker-compose.yml -OutFile docker-compose.yml

3. Start the backend

From the same folder, run:

docker compose up -d

The first start downloads about 2 GB of images, so it can take a few minutes. After that, the backend starts in under a minute.

Check that it's up:

curl http://localhost:8080/api/v1/health

When that returns a response, the backend is ready. You can also open http://localhost:8080/api/v1/health in a browser.

What's running

docker compose ps lists these containers:

Container Role
api-gateway Single entry point for the desktop app, on port 8080
experiment-service Plans and orchestrates scans
acquisition-service Drives the laser and detector (simulated for now)
processing-service Builds and calibrates spectral cubes, imports files
inference-service Classification models and built-in spectral index definitions
metadata-service Stores experiments and runs (PostgreSQL)
data-service Stores frames, cubes and results
kafka Message bus that streams frames and cubes between services
postgres Database for the metadata service

Only the gateway is reachable from outside Docker, and by default only from this computer. System architecture explains how the pieces work together.

4. Connect the desktop app

Open QCLM. With the backend on the same computer, the app connects automatically. The status bar shows the server latency, and Test Connection under Customize → Backend reports Connected.

If the backend runs on a different machine, see Using a shared lab server.

Everyday commands

Run these from the folder that contains docker-compose.yml.

Task Command
Start docker compose up -d
Stop (data is kept) docker compose down
Status docker compose ps
Logs (all services) docker compose logs -f
Logs (one service) docker compose logs -f processing-service

The backend restarts automatically with Docker, so after a reboot it comes back on its own once Docker is running.

Updating

docker compose pull
docker compose up -d

Keep the backend and desktop app on the same release. To pin a specific version instead of latest, create a file named .env next to docker-compose.yml:

QCLM_VERSION=2026.1.0

Using a shared lab server

You can run one backend on a lab workstation and connect several desktop apps to it.

  1. On the server, create a .env file next to docker-compose.yml so the gateway listens on the network:

    QCLM_BIND=0.0.0.0

  2. Restart the backend with docker compose up -d.

  3. On each client, open Customize → Backend (or gear button → Settings) and set Server URL to http://<server-name-or-ip>:8080/api/v1. Click Test Connection, then OK.

Only on a trusted network

In this default configuration the backend has no login: anyone who can reach port 8080 can read and change data. Only expose it on a trusted lab network, behind a firewall, and never directly to the internet.

Removing the backend

docker compose down        # stop and remove the containers, keep the data
docker compose down -v     # also delete all stored data (cannot be undone)

Your data lives in the Docker volumes qclm_postgres-data, qclm_kafka-data and qclm_qclm-data until you remove them.

Next: First run