Installation

This guide covers different methods to install and run Vespa, from quick local development setups to production deployments.

System Requirements

Before installing Vespa, ensure your system meets these requirements:

CPU Architecture

x86_64 (AMD64) or ARM64

Memory

Minimum 4GB RAM, 8GB+ recommended

Operating System

Linux (AlmaLinux 8, Ubuntu, etc.)

Java

Java 17 or later (for building applications)

For production deployments, consider Vespa Cloud for managed hosting with automated scaling, monitoring, and updates.

Installation Methods

Choose the installation method that best fits your needs:

Docker (Recommended)
Package Managers
Build from Source
Vespa Cloud

Docker is the quickest way to get started with Vespa and is suitable for development and testing.

Prerequisites

Docker Desktop or Docker Engine 20.10+
At least 4GB RAM allocated to Docker

Quick Start

Pull the Vespa image

docker pull vespaengine/vespa

Run Vespa

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

Verify installation

Wait for Vespa to be ready:

docker exec vespa bash -c 'while [[ "$(curl -s -o /dev/null -w ''%{http_code}'' http://localhost:19071/state/v1/health)" != "200" ]]; do sleep 1; done'
echo "Vespa is ready!"

Port Configuration

The default ports are:

Port	Service
8080	Query and Document API
19071	Config server
19050	Node admin (internal)
19092	Metrics (Prometheus format)

Docker Compose

For more complex setups, use Docker Compose:

docker-compose.yml

version: '3'
services:
  vespa:
    image: vespaengine/vespa
    hostname: vespa-container
    container_name: vespa
    ports:
      - "8080:8080"
      - "19071:19071"
    volumes:
      - vespa-data:/opt/vespa/var
    environment:
      - VESPA_CONFIGSERVERS=vespa-container
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:19071/state/v1/health"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  vespa-data:

Run with:

docker-compose up -d

Multi-node Setup with Docker

For testing distributed deployments:

docker-compose-multinode.yml

version: '3'
services:
  config:
    image: vespaengine/vespa
    hostname: config
    command: configserver
    ports:
      - "19071:19071"
    environment:
      - VESPA_CONFIGSERVERS=config
  
  node1:
    image: vespaengine/vespa
    hostname: node1
    depends_on:
      - config
    environment:
      - VESPA_CONFIGSERVERS=config
  
  node2:
    image: vespaengine/vespa
    hostname: node2
    depends_on:
      - config
    environment:
      - VESPA_CONFIGSERVERS=config
  
  container:
    image: vespaengine/vespa
    hostname: container
    depends_on:
      - config
    ports:
      - "8080:8080"
    environment:
      - VESPA_CONFIGSERVERS=config

Install Vespa directly on Linux systems using package managers.

RPM (Red Hat, CentOS, AlmaLinux)

Add Vespa repository

sudo dnf config-manager --add-repo \
  https://copr.fedorainfracloud.org/coprs/g/vespa/vespa/repo/epel-8/group_vespa-vespa-epel-8.repo

Install Vespa

sudo dnf install vespa

Start Vespa services

sudo systemctl start vespa-configserver
sudo systemctl start vespa

DEB (Ubuntu, Debian)

Add Vespa repository

sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL https://vespa.ai/keys/vespa.gpg | sudo gpg --dearmor -o /usr/share/keyrings/vespa-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/vespa-archive-keyring.gpg] https://vespa.ai/repo/vespa ubuntu main" | sudo tee /etc/apt/sources.list.d/vespa.list

Install Vespa

sudo apt-get update
sudo apt-get install -y vespa

Start Vespa services

sudo systemctl start vespa-configserver
sudo systemctl start vespa

Verify Installation

# Check service status
sudo systemctl status vespa

# Check config server
curl http://localhost:19071/state/v1/health

Build Vespa from source for development or custom deployments.

Prerequisites

Building Vespa requires:

Java 17 or later
Maven 3.8+
C++ compiler (GCC 12+ or Clang)
CMake 3.23+
AlmaLinux 8 (recommended for full build)

Building the complete Vespa codebase (C++ and Java) is only supported on AlmaLinux 8. The Java modules can be built on any platform with Java 17+ and Maven 3.8+.

Java-only Build

For application development and testing:

Clone the repository

git clone https://github.com/vespa-engine/vespa.git
cd vespa

Set up environment

export MAVEN_OPTS="-Xms128m -Xmx1024m"

Build Java modules

./bootstrap.sh java
mvn install --threads 1C

This builds all Java modules using one thread per CPU core.

Full Build (C++ and Java)

For complete Vespa development:

Set up development environment

Use the Docker development image:

docker pull vespaengine/vespa-dev-almalinux-8:latest
docker run -ti -v $(pwd):/vespa --entrypoint /bin/bash \
  vespaengine/vespa-dev-almalinux-8:latest

See the development guide for details.

Build Vespa

Inside the container:

cd /vespa
./bootstrap.sh full
mvn install --threads 1C

macOS Development Setup

For Java module development on macOS:

Install dependencies

brew install jenv mvnvm openjdk@17

Configure environment

# Link OpenJDK
sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk \
  /Library/Java/JavaVirtualMachines/openjdk-17.jdk

# Set up jEnv (for zsh)
echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(jenv init -)"' >> ~/.zshrc
eval "$(jenv init -)"
jenv enable-plugin export
jenv add $(/usr/libexec/java_home -v 17)

On ARM Macs, install Rosetta

Required for gRPC compatibility:

softwareupdate --install-rosetta

Verify setup

mvn -v

Should show Java 17 and Maven 3.8+.

Repository Structure

The Vespa codebase contains ~1.7 million lines of code across 150+ modules:

container-search: Query processing framework
searchcore: Core indexing and matching (C++)
searchlib: Ranking and feature libraries (C++)
configserver: Configuration management
document: Document model (Java and C++)

See Code-map.md for a complete overview.

Use managed Vespa Cloud for production deployments.

Benefits

Automated scaling and capacity management
Continuous deployment and rollback
Multi-region replication
Built-in monitoring and alerting
Security and compliance

Getting Started

Create a free account at console.vespa-cloud.com

Install Vespa CLI

# macOS
brew install vespa-cli

# Linux
curl -fsSL https://dl.vespa.ai/vespa-cli/install.sh | sh

Authenticate

vespa auth login

Deploy your application

vespa deploy --wait 300

Free Trial

Vespa Cloud offers a free tier for development and testing. Visit vespa.ai/free-trial to get started.

Vespa CLI

The Vespa CLI is a command-line tool for managing Vespa applications.

Installation

brew install vespa-cli

Common Commands

# Deploy an application
vespa deploy

# Query
vespa query 'select * from music where true'

# Feed a document
vespa document put id:music:music::1 doc.json

# Check status
vespa status

# View logs
vespa log

See the Vespa CLI reference for complete documentation.

Production Considerations

When deploying Vespa in production, consider:

Hardware Requirements

Config Server

2+ CPU cores
4GB+ RAM
50GB+ disk
Odd number (1, 3, or 5)

Container Nodes

4+ CPU cores
8GB+ RAM
Scales horizontally

Content Nodes

8+ CPU cores
16GB+ RAM
Fast SSD storage
Size based on data volume

Network

Low latency between nodes
1Gbps+ bandwidth
Reliable connections

Multi-node Setup

For production, deploy Vespa across multiple nodes:

Config server cluster: 3 nodes for high availability
Container cluster: Scale based on query load
Content cluster: Scale based on data size and redundancy needs

Example services.xml for multi-node:

<?xml version="1.0" encoding="UTF-8"?>
<services version="1.0">
    <admin version="2.0">
        <adminserver hostalias="admin0"/>
        <configservers>
            <configserver hostalias="config0"/>
            <configserver hostalias="config1"/>
            <configserver hostalias="config2"/>
        </configservers>
    </admin>
    
    <container id="default" version="1.0">
        <search/>
        <document-api/>
        <nodes>
            <node hostalias="container0"/>
            <node hostalias="container1"/>
            <node hostalias="container2"/>
        </nodes>
    </container>
    
    <content id="content" version="1.0">
        <redundancy>2</redundancy>
        <documents>
            <document type="music" mode="index"/>
        </documents>
        <nodes>
            <node hostalias="content0" distribution-key="0"/>
            <node hostalias="content1" distribution-key="1"/>
            <node hostalias="content2" distribution-key="2"/>
        </nodes>
    </content>
</services>

See multinode systems for complete documentation.

Monitoring

Vespa exposes metrics in Prometheus format:

curl http://localhost:19092/prometheus/v1/values

Key metrics to monitor:

Query latency (p50, p95, p99)
Query throughput
Feed throughput
Disk usage
Memory usage
CPU usage

Security

For production deployments:

Enable TLS for all endpoints
Configure authentication and authorization
Use firewall rules to restrict access
Regular security updates

See securing Vespa for details.

Next Steps

Quickstart

Build your first application

Sample Apps

Explore example applications

Multi-node Setup

Deploy a distributed cluster

Operations

Learn about running Vespa

Troubleshooting

Container won't start

Check Docker resource limits:

docker stats vespa

Vespa needs at least 4GB RAM. Increase Docker’s memory limit if needed.

Config server not responding

Verify the config server is running:

docker exec vespa systemctl status vespa-configserver

Check logs:

docker exec vespa vespa-logfmt | grep configserver

Build fails on macOS

For ARM Macs, ensure Rosetta is installed:

softwareupdate --install-rosetta

Verify Java version:

java -version  # Should be 17+
mvn -v         # Should use Java 17+

Out of memory errors

Increase JVM memory for Maven:

export MAVEN_OPTS="-Xms256m -Xmx2048m"

For Docker, increase container memory limits.

Get Started

Core Concepts

Search & Query

Data Operations

Machine Learning

Configuration & Deployment

Performance & Operations

Documentation Index

​System Requirements

CPU Architecture

Memory

Operating System

Java

​Installation Methods

​Prerequisites

​Quick Start

​Port Configuration

​Docker Compose

​Multi-node Setup with Docker

​RPM (Red Hat, CentOS, AlmaLinux)

​DEB (Ubuntu, Debian)

​Verify Installation

​Prerequisites

​Java-only Build

​Full Build (C++ and Java)

​macOS Development Setup

​Repository Structure

​Benefits

​Getting Started

​Free Trial

​Vespa CLI

​Installation

​Common Commands

​Production Considerations

​Hardware Requirements

Config Server

Container Nodes

Content Nodes

Network

​Multi-node Setup

​Monitoring

​Security

​Next Steps

Quickstart

Sample Apps

Multi-node Setup

Operations

​Troubleshooting

​Additional Resources

System Requirements

Installation Methods

Prerequisites

Quick Start

Port Configuration

Docker Compose

Multi-node Setup with Docker

RPM (Red Hat, CentOS, AlmaLinux)

DEB (Ubuntu, Debian)

Verify Installation

Prerequisites

Java-only Build

Full Build (C++ and Java)

macOS Development Setup

Repository Structure

Benefits

Getting Started

Free Trial

Vespa CLI

Installation

Common Commands

Production Considerations

Hardware Requirements

Multi-node Setup

Monitoring

Security

Next Steps

Troubleshooting

Additional Resources