Skip to main content
Vespa is a large-scale open-source project with approximately 1.7 million lines of code, split roughly equally between Java and C++. This guide will help you set up your development environment and understand the contribution workflow.

​
Prerequisites

Before you begin developing Vespa, you’ll need:
  • For Java development: Java 17 and Maven 3.8+
  • For C++ development: AlmaLinux 8 environment (recommended via Docker)
  • Version control: Git
  • Build tools: CMake (for C++ modules)

​
Development Environments

C++ and Java building is fully supported on AlmaLinux 8. This is the recommended environment for complete Vespa development.The easiest way to set up a complete development environment is using Docker:
# Use the official Vespa development Docker image
docker pull vespaengine/vespa-dev-almalinux-8
See the Vespa development on AlmaLinux 8 guide for detailed setup instructions.

​
Repository Structure

The Vespa codebase is organized as a flat structure of approximately 150 modules: 
vespa/
├── bootstrap.sh          # Build initialization script
├── CMakeLists.txt        # Top-level C++ build configuration
├── pom.xml              # Top-level Java build configuration
├── container-*/         # Container (jDisc) modules
├── searchcore/          # Content node core functionality
├── searchlib/           # Search and ranking libraries
├── config*/             # Configuration system modules
├── vespalib/            # C++ utility library
├── vespajlib/           # Java utility library
└── ...
For a detailed guide to the codebase structure, see the Code Map.

​
Quick Start

To verify your development environment:
1

Clone the repository

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

Build Java modules

export MAVEN_OPTS="-Xms128m -Xmx1024m"
./bootstrap.sh java
mvn install --threads 1C
3

Run tests

mvn test
For detailed building instructions, see Building Vespa.

​
Development Workflow

All work on Vespa happens directly on GitHub using the GitHub flow model.
Vespa follows an open development model:
  1. Master branch is stable: A new release is made from master every morning CET, Monday through Thursday
  2. Continuous integration: All commits are tested at factory.vespa.ai
  3. Pull request reviews: All PRs must be approved by a Vespa Committer
  4. Find reviewers: Check the OWNERS file in the relevant source directory

​
Creating a Pull Request

1

Follow best practices

Follow Git commit best practices when creating commits.
2

Submit your PR

When your code is ready, submit a pull request with a clear description of your changes.
3

Confirm licensing

All contributions include this confirmation:
I confirm that this contribution is made under the terms of the license found in the root directory of this repository’s source tree and that I have the authority necessary to make this contribution on behalf of its copyright owner.

​
API Compatibility

Vespa uses semantic versioning. Important compatibility rules:
  • Any Java API in a package with @PublicAPI annotation (and no @Beta on the class) cannot be changed incompatibly between major versions
  • Existing types and method signatures must be preserved (but can be marked deprecated)
  • ABI compatibility is verified during the Maven build (mvn install)
  • If you add to public APIs, update the ABI spec as instructed in the error message

​
Testing

Vespa has comprehensive test suites:
  • Unit tests: Java (JUnit) and C++ (Google Test)
  • Integration tests: System-level testing
  • Shell script tests: Using BATS
See Testing for detailed testing instructions.

​
Community and Support

Slack Community

Join the Vespa Slack for questions, discussions, and support

GitHub Issues

Report bugs, request features, or browse existing issues

Stack Overflow

Search or ask questions tagged with ‘vespa’

Vespa Blog

Follow feature updates and use cases

​
Next Steps

Building Vespa

Learn how to build Vespa from source

Code Map

Navigate the codebase structure

Running Tests

Run and write tests for Vespa

Contributing Guide

Detailed contribution guidelines

Build docs developers (and LLMs) love

Get started for freeTalk to us