Docker | QALITA Documentation

The QALITA Worker Docker image allows you to use the QALITA CLI ready-to-use in any environment.

Image renamed

The image now lives at qalita/cli (Docker Hub) and ghcr.io/qalita/cli. The legacy name qalita/qalita-cli is frozen and no longer receives updates — update your pulls and deployment scripts.

Image layout — read this first

The image runs as the non-root user qalita (uid 10001), as required by least-privilege policies (runAsNonRoot). This changed two things compared to the legacy root-based worker image:

Aspect	Legacy image (root)	Current image `qalita/cli`
User	`root` (uid 0)	`qalita` (uid 10001)
State directory	`/root/.qalita`	`/home/qalita/.qalita`
Volume mount point	`-v …:/root/.qalita`	`-v …:/home/qalita/.qalita`

Everything the worker persists — registration file .worker, sources-conf.yaml, jobs/, logs — lives under /home/qalita/.qalita. Mount your volume there, and give the host directory to uid 10001:

sudo chown -R 10001:10001 /srv/qalita

The #1 deployment mistake

A host directory owned by root and bind-mounted into the container is readable but not writable by uid 10001. The symptom is a loop of [Errno 13] Permission denied messages, no logs on disk, and a worker that never registers. The chown above fixes it. If you migrate from the legacy image, also delete the stale .current_env file from the volume: it contains a path from the old layout.

Quick Start

docker run qalita/cli <your_qalita_cli_command>

To see all available CLI commands, go to the command details page.

How to Use It ?

Worker with UI (recommended)

The trailing worker run command makes the worker run in the foreground — its whole output lands in docker logs — while the supervision UI runs in the background:

docker run -d --name qalita-worker --restart unless-stopped \
  -v /srv/qalita:/home/qalita/.qalita \
  -e QALITA_WORKER_NAME=worker-1 \
  -e QALITA_WORKER_MODE=worker \
  -e QALITA_WORKER_ENDPOINT=https://backend.example.com:3080 \
  -e QALITA_WORKER_TOKEN=***** \
  -e QALITA_WORKER_UI=true \
  -e QALITA_WORKER_UI_PORT=7070 \
  -e QALITA_WORKER_UI_HOST=0.0.0.0 \
  -p 7070:7070 \
  qalita/cli worker run

Follow the startup with docker logs -f qalita-worker — expect Authenticated as <email> then Worker '<name>' registered with ID <n>.

note

With this pattern the worker is already running: do not also press “Start” in the UI, it would spawn a second worker process.

Minimal Configuration

This will only run a worker waiting for tasks to run — no UI, no persistence.

docker run \
-e QALITA_WORKER_NAME=worker \
-e QALITA_WORKER_MODE=worker \
-e QALITA_WORKER_ENDPOINT=http://localhost:3080 \
-e QALITA_WORKER_TOKEN=***** \
qalita/cli worker run

UI only

Without a trailing command, the entrypoint starts only the web UI.

warning

The worker is not running by default, you will have to enable it in the UI. Its output then goes to /home/qalita/.qalita/worker_run.log, not to docker logs — see Where are the logs? below.

docker run \
-v /srv/qalita:/home/qalita/.qalita \
-e QALITA_WORKER_NAME=worker \
-e QALITA_WORKER_MODE=worker \
-e QALITA_WORKER_ENDPOINT=http://localhost:3080 \
-e QALITA_WORKER_TOKEN=***** \
-e QALITA_WORKER_UI=true \
-e QALITA_WORKER_UI_PORT=7070 \
-e QALITA_WORKER_UI_HOST=0.0.0.0 \
-p 7070:7070  \
qalita/cli

Private PKI / internal CA

On-premise platforms often serve HTTPS with certificates issued by an internal root CA. Neither requests (REST) nor gRPC read the operating system trust store, so the CA bundle (PEM, root + intermediates) must be handed to both stacks:

sudo mkdir -p /srv/qalita/certs
sudo cp ca-bundle.pem /srv/qalita/certs/
sudo chown -R 10001:10001 /srv/qalita

docker run ... \
  -v /srv/qalita:/home/qalita/.qalita \
  -e REQUESTS_CA_BUNDLE=/home/qalita/.qalita/certs/ca-bundle.pem \
  -e GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/home/qalita/.qalita/certs/ca-bundle.pem \
  ... \
  qalita/cli worker run

warning

SKIP_SSL_VERIFY=true disables certificate validation for REST requests only and never for gRPC — it is a diagnostic tool, not a deployment option. With a private PKI, the two CA variables above are the supported path. Also make sure any reverse proxy in front of the gRPC port forwards HTTP/2 (nginx: grpc_pass; HAProxy: alpn h2).

About `QALITA_HOME`

QALITA_HOME always designates a path inside the container (default: /home/qalita/.qalita) — never the host path of your volume. It is honored by CLI ≥ 2.18.2; older versions silently ignored it. Mounting your volume on /home/qalita/.qalita and leaving QALITA_HOME unset is the portable pattern that works on every version.

Where are the logs?

Worker started with a trailing worker run command (recommended): everything is in docker logs -f qalita-worker.
Worker started from the UI: output goes to /home/qalita/.qalita/worker_run.log, and the file is archived as worker_run_<timestamp>.log whenever the process stops. Read it with a wildcard:

docker exec qalita-worker sh -c 'cat /home/qalita/.qalita/worker_run*.log'

Mount a local `sources-conf.yaml`

If you want to persist only your source configuration, you can mount a single file instead of the whole state directory:

docker run \
-v ${HOME}/.qalita/sources-conf.yaml:/home/qalita/.qalita/sources-conf.yaml \
-e QALITA_WORKER_NAME=worker \
-e QALITA_WORKER_MODE=worker \
-e QALITA_WORKER_ENDPOINT=http://localhost:3080 \
-e QALITA_WORKER_TOKEN=***** \
qalita/cli worker run

Chain CLI commands

The image entrypoint prepends qalita to whatever you pass, so docker run … qalita/cli worker run runs qalita worker run. Chaining two commands therefore needs a shell: override the entrypoint with sh -c and write the full qalita … invocations inside the quoted string.

Get the List of QALITA Packs

docker run \
-v ${HOME}/.qalita/sources-conf.yaml:/home/qalita/.qalita/sources-conf.yaml \
-e QALITA_WORKER_NAME=worker \
-e QALITA_WORKER_MODE=worker \
-e QALITA_WORKER_ENDPOINT=http://localhost:3080 \
-e QALITA_WORKER_TOKEN=***** \
--entrypoint sh \
qalita/cli \
-c "qalita worker login && qalita pack list"

Get the List of QALITA Sources

docker run \
-v ${HOME}/.qalita/sources-conf.yaml:/home/qalita/.qalita/sources-conf.yaml \
-e QALITA_WORKER_NAME=worker \
-e QALITA_WORKER_MODE=worker \
-e QALITA_WORKER_ENDPOINT=http://localhost:3080 \
-e QALITA_WORKER_TOKEN=***** \
--entrypoint sh \
qalita/cli \
-c "qalita worker login && qalita source list"

Environment variables

To find more details about env vars go to the dedicated page

Image layout — read this first​

Tags​

Quick Start​

How to Use It ?​

Worker with UI (recommended)​

Minimal Configuration​

UI only​

Private PKI / internal CA​

About QALITA_HOME​

Where are the logs?​

Mount a local sources-conf.yaml​

Chain CLI commands​

Get the List of QALITA Packs​

Get the List of QALITA Sources​

Environment variables​