Vespa quick start using Docker

This guide describes how to install and run Vespa on a single machine using Docker. Also try the CentOS / Vagrant or Windows guide.


  • Docker installed.
  • Git installed.
  • Operating system: macOS or Linux
  • Architecture: x86_64
  • At least 2GB of memory dedicated to your container instance.

  1. Clone the Vespa sample apps from github:
    $ git clone
    $ export VESPA_SAMPLE_APPS=`pwd`/sample-apps
  2. 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. Publish port 8080 to make the search and feed interfaces accessible outside of the docker container. Only one docker container named vespa can run at a time, change name if needed.

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

  3. Wait for configuration server to start - wait for a 200 OK response:
    $ docker exec vespa bash -c 'curl -s --head http://localhost:19071/ApplicationStatus'
  4. Deploy and activate a sample application:
    $ docker exec vespa bash -c '/opt/vespa/bin/vespa-deploy prepare /vespa-sample-apps/basic-search/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.
  5. Ensure the application is active - wait for a 200 OK response:
    $ curl -s --head http://localhost:8080/ApplicationStatus
  6. Feed documents:
    $ curl -s -X POST --data-binary @${VESPA_SAMPLE_APPS}/basic-search/music-data-1.json \
        http://localhost:8080/document/v1/music/music/docid/1 | python -m json.tool
    $ curl -s -X POST --data-binary @${VESPA_SAMPLE_APPS}/basic-search/music-data-2.json \
        http://localhost:8080/document/v1/music/music/docid/2 | python -m json.tool
    This uses the document API. Use the Java Feeding API to feed large amounts of data fast.
  7. Run a query and a document get request :
    $ curl -s http://localhost:8080/search/?query=bad | python -m json.tool
    $ curl -s http://localhost:8080/document/v1/music/music/docid/2 | python -m json.tool
    View the results in a browser at http://localhost:8080/search/?query=bad. Read more in the Search API.
  8. Clean up when you're done

    Stop the running container when you no longer need it:

    $ docker stop vespa

    Optionally, remove the stopped container entirely:

    $ docker rm vespa

Next Steps