How to Deploy Vespa with Docker for AI-Powered Search

Getting Started with Vespa in 5 Minutes

Vespa is a powerful AI search platform that combines vector search, full-text search, and ML model inference in a single system. Thanks to its official Docker image, getting a Vespa instance up and running locally takes just a few commands. This guide walks you through deploying Vespa with Docker, feeding it data, and running your first hybrid search query.

Prerequisites

Docker installed on your machine (20.10+ recommended)
At least 4 GB of RAM allocated to Docker
A terminal with curl for testing queries

Step 1: Pull and Run Vespa

The official Vespa Docker image includes everything you need: the config server, content nodes, and the container orchestrator. Start a single-node instance with:

docker pull vespaengine/vespa:latest
docker run --detach --name vespa --hostname vespa-container \
  --publish 8080:8080 --publish 19071:19071 \
  vespaengine/vespa:latest

Port 8080 is the query and feed endpoint, and port 19071 is the config server (used to deploy applications). Wait about 30 seconds for the services to start, then verify with:

curl -s http://localhost:19071/state/v1/health | head

Step 2: Deploy a Simple Search Application

Vespa uses application packages to define document schemas, ranking profiles, and indexing settings. Create a minimal schema for semantic search over text documents:

mkdir -p myapp/schemas
cat > myapp/schemas/doc.sd << 'EOF'
schema doc {
  document doc {
    field title type string {
      indexing: index | summary
    }
    field body type string {
      indexing: index | summary
    }
  }
}
EOF
cat > myapp/services.xml << 'EOF'
<?xml version="1.0" encoding="utf-8"?>
<services version="1.0">
  <admin version="2.0">
    <adminserver hostalias="node1"/>
  </admin>
  <content id="doc" version="1.0">
    <documents>
      <document type="doc" mode="index"/>
    </documents>
    <nodes>
      <node hostalias="node1" distribution-key="0"/>
    </nodes>
  </content>
</services>
EOF

Deploy the application package:

zip -r myapp.zip myapp/
curl -s --header "Content-Type: application/zip" \
  --data-binary @myapp.zip \
  http://localhost:19071/application/v2/tenant/default/prepareandactivate

Step 3: Feed Documents and Query

Feed documents using Vespa's JSON feed format:

curl -s -X POST http://localhost:8080/document/v1/doc/doc/docid/1 \
  -H "Content-Type: application/json" \
  -d '{"fields": {"title": "Vespa AI Search", "body": "Vespa is the AI search platform for large-scale RAG and recommendations."}}'

curl -s -X POST http://localhost:8080/document/v1/doc/doc/docid/2 \
  -H "Content-Type: application/json" \
  -d '{"fields": {"title": "Docker Container Guide", "body": "How to deploy applications using Docker containers."}}'

Now search with a simple query:

curl -s "http://localhost:8080/search/?yql=select+*+from+doc+where+title+contains+%27ai%27&format=json"

Adding Vector Search

To enable vector search (neural search), add a tensor field to your schema, deploy a BERT-based embedding model, and use approximate nearest neighbor search. Vespa natively supports ONNX models for real-time embedding during indexing and query time, making it an excellent backend for RAG pipelines.

Why Vespa Excels for AI Workloads

Unlike Elasticsearch or standalone vector databases, Vespa evaluates ranking expressions — including ML model outputs — at query time. This means you can combine BM25 textual relevance with dense vector similarity and business-specific ranking signals in a single request, all with sub-100ms latency at billion-document scale.

Next Steps

Once your Vespa instance is running, explore the official Vespa documentation for advanced features like multi-vector ranking, grouping, tensor computations, and distributed deployment across data centers. Vespa's Docker setup makes it easy to transition from a local prototype to a production cluster.