Quick Start

This guide describes how to install and run Vespa on a single machine using Docker. Once you have completed the steps in this guide, you have a running Vespa instance with searchable documents in it and will have run some search queries against them.

Also try the CentOS / Vagrant or Windows guide.


  • Docker installed.
  • Git installed.
  • Operating system: macOS or Linux
  • Architecture: x86_64
  • Minimum 6GB memory dedicated to Docker (the default is 2GB on Macs).
This guide is tested with Docker for Mac, Community Edition-18.06.1-ce-mac73 (26764) and vespaengine/vespa Docker image built 2018-10-01.

Running Vespa in Docker

  1. Validate environment:

    $ docker info | grep "Total Memory"

    Make sure you see something like Total Memory: 5.818GiB

  2. Clone the Vespa sample apps from github:

    $ git clone https://github.com/vespa-engine/sample-apps.git
    $ export VESPA_SAMPLE_APPS=`pwd`/sample-apps
  3. Start a Vespa Docker container:

    $ docker run --detach --name vespa --hostname vespa-container --privileged \
      --volume $VESPA_SAMPLE_APPS:/vespa-sample-apps --publish 8080:8080 vespaengine/vespa

    The volume option makes the previously downloaded source code available as /vespa-sample-apps inside the docker container. The port 8080 is published to make the search and feed interfaces accessible outside of the docker container. Only one docker container named vespa can run at a time so change the name if needed.

    If you're interested in the exact steps performed by the above command, please see the Dockerfile and the startup script.

  4. Wait for the configuration server to start - signified by a 200 OK response:

    $ docker exec vespa bash -c 'curl -s --head http://localhost:19071/ApplicationStatus'
  5. Deploy and activate a sample application:

    $ docker exec vespa bash -c '/opt/vespa/bin/vespa-deploy prepare \
      /vespa-sample-apps/album-recommendation-selfhosted/src/main/application/ && \
      /opt/vespa/bin/vespa-deploy activate'

    More sample applications can be found in sample-apps. Read more on applications in Application packages.

  6. Ensure the application is active - wait for a 200 OK response:

    $ curl -s --head http://localhost:8080/ApplicationStatus
  7. Feed documents:

    $ curl -H "Content-Type:application/json" --data-binary @${VESPA_SAMPLE_APPS}/album-recommendation-selfhosted/src/test/resources/A-Head-Full-of-Dreams.json \
    $ curl -H "Content-Type:application/json" --data-binary @${VESPA_SAMPLE_APPS}/album-recommendation-selfhosted/src/test/resources/Love-Is-Here-To-Stay.json \
    $ curl -H "Content-Type:application/json" --data-binary @${VESPA_SAMPLE_APPS}/album-recommendation-selfhosted/src/test/resources/Hardwired...To-Self-Destruct.json \

    This uses /document/v1/ - use vespa-http-client to feed large amounts of data, fast.

  8. Make a query:

    $ curl "http://localhost:8080/search/?ranking=rank_albums&yql=select%20%2A%20from%20sources%20%2A%20where%20sddocname%20contains%20%22music%22%3B&ranking.features.query(user_profile)=%7B%7Bcat%3Apop%7D%3A0.8%2C%7Bcat%3Arock%7D%3A0.2%2C%7Bcat%3Ajazz%7D%3A0.1%7D"

    You can also view query results in a browser with the query builder UI at http://localhost:8080/querybuilder/. The query builder has guided queries and YQL autocompletion. Read more in the Query API.

  9. Run a document GET request:

    $ curl -s http://localhost:8080/document/v1/mynamespace/music/docid/2
  10. Clean up:

    $ docker rm -f vespa


See troubleshooting. For json pretty-print, append

| python -m json.tool
to commands that output json.

Next Steps