Docker

The official GalaxDB Docker image is harbi256/galaxdb:latest. It includes both galaxdb-server and galaxdb-sidecar.

Quick Start

Run GalaxDB without embeddings (SQL + HNSW vector search only):

bash

docker run -d \
  --name galaxdb \
  -p 5433:5433 \
  -p 9090:9090 \
  -v galaxdb_data:/data \
  harbi256/galaxdb:latest \
  --data-dir /data

bash

# Verify it's running
curl http://localhost:9090/health
# {"status":"ok","version":"1.0.0-beta.1","subsystems":{"disk_full":false,"sidecar_healthy":false,"connections_active":0}}

With Embeddings

Enable full AI features by passing the sidecar and model flags. Mount the HuggingFace cache to avoid re-downloading the model on every container start.

bash

docker run -d \
  --name galaxdb \
  -p 5433:5433 \
  -p 9090:9090 \
  -v galaxdb_data:/data \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  harbi256/galaxdb:latest \
  --data-dir /data \
  --port 5433 \
  --observe-port 9090 \
  --sidecar /usr/local/bin/galaxdb-sidecar \
  --model sentence-transformers/all-MiniLM-L6-v2

bash

# Wait for sidecar to load model, then verify
curl http://localhost:9090/health
# {"status":"ok","version":"1.0.0-beta.1","subsystems":{"disk_full":false,"sidecar_healthy":true,"connections_active":0}}

Tip

The first run downloads the model (~90 MB for all-MiniLM-L6-v2). With the HuggingFace cache mounted, subsequent starts use the cached model and come up in seconds.

Volumes

Volume	Purpose	Required
/data	Database files (WAL, SST, HNSW index)	Yes (for persistence)
/root/.cache/huggingface	HuggingFace model cache	Recommended

Warning

Without a volume for /data, all database data is lost when the container stops. Always mount a persistent volume in production.

Environment Variables

bash

# Enable encryption at rest with a local key file
docker run -d \
  -p 5433:5433 \
  -v galaxdb_data:/data \
  -v /path/to/key.bin:/secrets/key.bin:ro \
  -e GALAXDB_KEY_PROVIDER=local:/secrets/key.bin \
  harbi256/galaxdb:latest \
  --data-dir /data

# Enable encryption with environment variable key
docker run -d \
  -p 5433:5433 \
  -v galaxdb_data:/data \
  -e GALAXDB_KEY_PROVIDER=env:GALAXDB_MASTER_KEY \
  -e GALAXDB_MASTER_KEY=0123456789abcdef... \
  harbi256/galaxdb:latest \
  --data-dir /data

# Set log level
docker run -d \
  -p 5433:5433 \
  -e GALAXDB_LOG_LEVEL=debug \
  harbi256/galaxdb:latest

View logs

bash

docker logs galaxdb
docker logs -f galaxdb  # follow

Stop and remove

bash

docker stop galaxdb
docker rm galaxdb

Configuration

Observability