Quick Start

This guide describes how to install and run Vespa on a single machine using Docker - it configures Vespa, feeds three documents and runs a query. See Getting Started for troubleshooting, next steps and other guides.


  • Docker Desktop on Mac or Docker on Linux
  • Git
  • 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 at minimum 6Gb.

  2. Clone the Vespa sample apps from github:

    $ git clone https://github.com/vespa-engine/sample-apps.git
    $ cd sample-apps/album-recommendation-selfhosted
  3. Start a Vespa Docker container:

    $ docker run --detach --name vespa --hostname vespa-container \
      --publish 8080:8080 --publish 19071:19071 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. See the Dockerfile and the startup script for more insights.

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

    $ curl -s --head http://localhost:19071/ApplicationStatus
  5. Deploy and activate a sample application:

    $ tar -C src/main/application -cf - . | gzip | \
      curl --header Content-Type:application/x-gzip --data-binary @- localhost:19071/application/v2/tenant/default/session
    $ curl -X PUT localhost:19071/application/v2/tenant/default/session/2/prepared
    $ curl -X PUT localhost:19071/application/v2/tenant/default/session/2/active

    The session id (here: 2) is returned in the first call - this increments with subsequent calls, for use in prepared and active calls. Read more on deploying 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 @src/test/resources/A-Head-Full-of-Dreams.json \
    $ curl -H Content-Type:application/json --data-binary @src/test/resources/Love-Is-Here-To-Stay.json \
    $ curl -H Content-Type:application/json --data-binary @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 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. Removing this setup:

    $ docker rm -f vespa
  11. Restarting Docker containers:

    If mapping file systems to the parent host and restarting the Docker container, see Running Docker containers in production for graceful shutdown timeout settings:

    $ docker stop vespa -t 120
    $ docker start vespa

Next steps

Check out getting started for more tutorials and use cases which Vespa is great for.