Skip to main content
Version: Latest (v2.3)

Docker

This guide describes how to run Spice.ai as a Docker container, either directly with docker run, with Docker Compose, or by building a custom image that bundles a Spicepod and data files. For Kubernetes deployments, see the Kubernetes deployment guide.

Quickstart​

Run the latest Spice.ai image with a local Spicepod mounted into the container:

docker run --rm -it \
  -p 8090:8090 \
  -p 9090:9090 \
  -p 50051:50051 \
  -v "$(pwd)":/app \
  spiceai/spiceai:latest

Spice listens on three ports:

  • 8090 — HTTP API and /health endpoint
  • 9090 — Prometheus metrics (optional)
  • 50051 — Arrow Flight (gRPC) for high-throughput query results

As of Spice v2.0, AI features (embeddings, local model inference, search) are included in the default image — no separate tag is required. The data-only image, without AI/ML dependencies, is published only in nightly builds for open source and is available as a production-ready distribution through Spice Cloud and Spice.ai Enterprise.

Browse all published tags at hub.docker.com/r/spiceai/spiceai/tags.

Prerequisites​

Image Tags​

TagDescription
latestLatest stable release. Includes AI features (embeddings, local model inference, vector search) by default.
<version>A specific stable release, e.g. 2.0.0. Recommended for production for reproducible deployments.
note

The -models image tags were removed in Spice v2.0 — AI/ML support is now part of the default image. The data-only image (without AI/ML dependencies) is published only in nightly builds for open source.

Pin to a specific version in production to avoid unexpected upgrades:

docker run -p 8090:8090 spiceai/spiceai:2.0.0

Run with Docker Compose​

docker-compose.yaml:

services:
  spiced:
    image: spiceai/spiceai:latest
    container_name: spiced
    ports:
      - '8090:8090'
      - '9090:9090'
      - '50051:50051'
    volumes:
      - ./spicepod.yaml:/app/spicepod.yaml:ro
      - ./data:/app/data
    env_file:
      - .env
    healthcheck:
      test: ['CMD', 'wget', '-q', '--spider', 'http://localhost:8090/health']
      interval: 10s
      timeout: 3s
      retries: 5
    restart: unless-stopped

Start the container:

docker compose up

Build a Custom Image​

For deployments that ship a Spicepod and data with the runtime, build a custom image that copies them in:

# AI features are included in the default image as of Spice v2.0.
# See https://hub.docker.com/r/spiceai/spiceai/tags for all tags.
FROM spiceai/spiceai:2.0.0

WORKDIR /app

# Spicepod definition
COPY spicepod.yaml ./

# Optional: bundled data files
COPY data ./data

# Optional: environment files (.env, .env.local). Avoid baking secrets
# into images — prefer runtime --env-file or a secret manager.
COPY .env* ./

# --metrics is optional; omit if Prometheus metrics are not needed.
CMD ["--http", "0.0.0.0:8090", "--metrics", "0.0.0.0:9090", "--flight", "0.0.0.0:50051"]

EXPOSE 8090 9090 50051

Build and run:

docker build -t my-spiceai-app .
docker run --rm -p 8090:8090 -p 50051:50051 my-spiceai-app
Do not bake secrets into images

Image layers are cached and distributed. Use --env-file, docker run -e, or a secret manager such as Docker secrets, HashiCorp Vault, or AWS Secrets Manager to inject credentials at runtime.

Environment Variables and Secrets​

Spice loads secrets from environment variables prefixed with SPICE_SECRET_. See the Environment Secret Store for details.

Pass secrets at runtime with --env-file (preferred) or -e:

docker run --rm -p 8090:8090 \
  -v "$(pwd)/spicepod.yaml":/app/spicepod.yaml:ro \
  --env-file .env \
  -e SPICED_LOG=INFO \
  spiceai/spiceai:latest

Common runtime variables:

VariablePurpose
SPICED_LOGLog level: ERROR, WARN, INFO, DEBUG, TRACE. Default INFO.
SPICE_SECRET_<NAME>Inject a named secret referenced from a Spicepod.
TMPDIRTemporary directory. From v2.3.1 the image sets it to /app/tmp; see Temporary files.

Persistence​

For workloads that use file-based acceleration (for example, DuckDB or SQLite), mount a host directory or named volume so data survives container restarts:

docker run --rm -p 8090:8090 \
  -v spice-data:/data \
  -v "$(pwd)/spicepod.yaml":/app/spicepod.yaml:ro \
  spiceai/spiceai:latest

In the Spicepod, configure the accelerator to write under the mount path, for example duckdb_file: /data/taxi_trips.db.

Temporary files​

The published images are built FROM scratch and contain only the files the runtime needs — there is no /tmp. From v2.3.1 the image therefore ships TMPDIR=/app/tmp and creates that directory owned by the nobody (65534) user it runs as, so anything resolving the OS temporary directory has somewhere to write. Acceleration snapshots stage their tar archive there before uploading, and it is also the default target for query spill when runtime.query.temp_directory is unset. On v2.3.0 the image sets no TMPDIR and has no such directory.

/app/tmp lives on the container's writable layer, which is usually small and is discarded when the container is removed. For workloads that snapshot large accelerations or spill large sorts and joins, give the temporary directory a volume of its own:

docker run --rm -p 8090:8090 \
  -v spice-tmp:/tmp-volume \
  -e TMPDIR=/tmp-volume \
  -v "$(pwd)/spicepod.yaml":/app/spicepod.yaml:ro \
  spiceai/spiceai:latest

Setting runtime.query.temp_directory in the Spicepod covers query spill specifically; TMPDIR covers everything else that asks the operating system for a temporary path.

Health Checks​

Spice exposes /health (process up) and /v1/ready (components ready) on the HTTP port. Use these in container orchestrators or load balancers:

curl http://localhost:8090/health
curl http://localhost:8090/v1/ready

A Docker Compose healthcheck example is included in the Run with Docker Compose section above.

Cookbook​