title: 'Docker' description: 'Run Spice.ai as a Docker container.' sidebar_label: 'Docker' sidebar_position: 4 tags:
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.
Run the latest Spice.ai image with a local Spicepod mounted into the container:
Spice listens on three ports:
8090 — HTTP API and /health endpoint9090 — Prometheus metrics (optional)50051 — Arrow Flight (gRPC) for high-throughput query resultsTo use AI features (embeddings, models, search), substitute the latest-models tag:
Browse all published tags at hub.docker.com/r/spiceai/spiceai/tags.
spicepod.yaml file. See Spicepods.| Tag | Description |
|---|---|
latest | Latest stable release. Excludes large model dependencies for a smaller image. |
latest-models | Latest stable release including AI features (embeddings, local model inference, vector search). |
<version> | A specific stable release, e.g. 1.11.5. Recommended for production for reproducible deployments. |
<version>-models | A specific stable release with AI features included. |
Pin to a specific version in production to avoid unexpected upgrades:
docker-compose.yaml:
Start the container:
For deployments that ship a Spicepod and data with the runtime, build a custom image that copies them in:
Build and run:
:::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, HashiCorp Vault, or AWS Secrets Manager to inject credentials at runtime.
:::
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:
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. |
For workloads that use file-based acceleration (for example, DuckDB or SQLite), mount a host directory or named volume so data survives container restarts:
In the Spicepod, configure the accelerator to write under the mount path, for example duckdb_file: /data/taxi_trips.db.
Spice exposes /health (process up) and /v1/ready (components ready) on the HTTP port. Use these in container orchestrators or load balancers:
A Docker Compose healthcheck example is included in the Run with Docker Compose section above.