Run DriftQ-Core locally

The 2-minute path to running DriftQ-Core on any machine with Docker. Use a pinned version for reproducible runs (recommended).

Option A (recommended): Pull from GHCR and run

Pin a version so your run is reproducible. latest tracks main (convenient, but can break unexpectedly).

mac/linux

export DRIFTQ_VERSION="1.0.0"
docker pull ghcr.io/driftq-org/driftq-core:$DRIFTQ_VERSION
docker run --rm -p 8080:8080 -v driftq-data:/data ghcr.io/driftq-org/driftq-core:$DRIFTQ_VERSION

windows powershell

$env:DRIFTQ_VERSION="1.0.0"
docker pull ghcr.io/driftq-org/driftq-core:$env:DRIFTQ_VERSION
docker run --rm -p 8080:8080 -v driftq-data:/data ghcr.io/driftq-org/driftq-core:$env:DRIFTQ_VERSION

verify

# mac/linux
curl http://localhost:8080/v1/version

# windows powershell
curl.exe http://localhost:8080/v1/version

Useful tags

• ghcr.io/driftq-org/driftq-core:1.0.0 (recommended: reproducible)
• ghcr.io/driftq-org/driftq-core:latest (tracks main)
• ghcr.io/driftq-org/driftq-core:sha-<...> (exact build)

Stop it with Ctrl+C. To wipe persisted WAL/data:

docker volume rm driftq-data

Option B: Docker Compose (recommended if you cloned the repo)

Compose uses a named volume so WAL persists. You can override the image tag with DRIFTQ_VERSION.

mac/linux

export DRIFTQ_VERSION="1.0.0"
docker compose up

windows powershell

$env:DRIFTQ_VERSION="1.0.0"
docker compose up

DriftQ listens on http://localhost:8080. WAL is stored in a named Docker volume mounted at /data inside the container.

stop

docker compose down

wipe WAL/data

docker compose down -v

minimal compose example (defaults to 1.0.0)

services:
  driftqd:
    image: ghcr.io/driftq-org/driftq-core:${DRIFTQ_VERSION:-1.0.0}
    ports:
      - "8080:8080"
    volumes:
      - driftq-data:/data

volumes:
  driftq-data:

Option C: Build locally (dev)

mac/linux

docker build -t driftq-core:local \
  --build-arg VERSION=dev \
  --build-arg COMMIT="$(git rev-parse --short HEAD)" \
  .

windows powershell

docker build -t driftq-core:local `
  --build-arg VERSION=dev `
  --build-arg COMMIT=$(git rev-parse --short HEAD) `
  .

run

docker run --rm -p 8080:8080 -v driftq-data:/data driftq-core:local

Note: this page mirrors the repo README