spiceai/docs

title: 'Docker' description: 'Run Spice.ai as a Docker container.' sidebar_label: 'Docker' sidebar_position: 4 tags:

deployment
docker
spiceai

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 (opens in a new tab).

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

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 (opens in a new tab).

Browse all published tags at hub.docker.com/r/spiceai/spiceai/tags (opens in a new tab).

Prerequisites

Docker Engine (opens in a new tab) 20.10 or newer (or Docker Desktop).
A spicepod.yaml file. See Spicepods (opens in a new tab).
Optional: Docker Compose v2 (opens in a new tab) for multi-container setups.

Image Tags

Tag	Description
`latest`	Latest 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

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

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

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

# 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

docker build -t my-spiceai-app .
docker run --rm -p 8090:8090 -p 50051:50051 my-spiceai-app

:::warning 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 (opens in a new tab), HashiCorp Vault (opens in a new tab), or AWS Secrets Manager (opens in a new tab) to inject credentials at runtime. :::

Environment Variables and Secrets

Spice loads secrets from environment variables prefixed with SPICE_SECRET_. See the Environment Secret Store (opens in a new tab) 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

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:

Variable	Purpose
`SPICED_LOG`	Log level: `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`. Default `INFO`.
`SPICE_SECRET_<NAME>`	Inject a named secret referenced from a Spicepod.
`TMPDIR`	Temporary directory. From v2.3.1 the image sets it to `/app/tmp`; see Temporary files (opens in a new tab).

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

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 (opens in a new tab) 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

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

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

A Docker Compose healthcheck example is included in the Run with Docker Compose (opens in a new tab) section above.

Cookbook

Running Spice.ai in Docker (opens in a new tab)

spiceai/docs/README.md