Vespa quick start using VirtualBox and Vagrant

edit page

This guide describes how to install and run Vespa on a single machine using Virtualbox and Vagrant. See Getting Started for troubleshooting, next steps and other guides.

Prerequisites:

• VirtualBox and Vagrant
• Git
• Operating system: macOS or Linux

1. Clone the Vespa sample apps from github:

   $ git clone https://github.com/vespa-engine/sample-apps.git
   

2. Start CentOS VM using Vagrant and Virtualbox:

   Navigate into the cloned repository and start the CentOS VM using Vagrant. This may take a couple of minutes.

   Installing the Vagrant VirtualBox guest plugin is required to mount the sample application directory inside the VM.

   Docker note: if you have completed the Docker guide, please stop the running Vespa container before proceeding. Otherwise you will receive conflicts due to the same port being forwarded from the host.

   $ cd sample-apps
   $ vagrant plugin install vagrant-vbguest
   $ vagrant up
   

   See the Vagrantfile in the sample-apps directory for exact configuration of the CentOS based VM.

3. SSH into the VM:

   $ vagrant ssh

4. Start the Vespa configuration server:

   $ sudo service vespa-configserver start

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

   $ curl -s --head http://localhost:19071/ApplicationStatus
   

6. Deploy a sample application:

   The sample apps are located at /vespa-sample-apps inside the VM.

   $ cd /vespa-sample-apps/album-recommendation-selfhosted
   $ vespa-deploy prepare src/main/application && vespa-deploy activate
   

7. Start Vespa:

   $ sudo service vespa start
   

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

   $ curl -s --head http://localhost:8080/ApplicationStatus
   

9. Feed documents:

   $ curl -s -H "Content-Type:application/json" --data-binary @/vespa-sample-apps/album-recommendation-selfhosted/src/test/resources/A-Head-Full-of-Dreams.json \
     http://localhost:8080/document/v1/mynamespace/music/docid/1
   $ curl -s -H "Content-Type:application/json" --data-binary @/vespa-sample-apps/album-recommendation-selfhosted/src/test/resources/Love-Is-Here-To-Stay.json \
     http://localhost:8080/document/v1/mynamespace/music/docid/2
   $ curl -s -H "Content-Type:application/json" --data-binary @/vespa-sample-apps/album-recommendation-selfhosted/src/test/resources/Hardwired...To-Self-Destruct.json \
     http://localhost:8080/document/v1/mynamespace/music/docid/3
   

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

10. 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"
    

    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.

11. Run a document get request:

    $ curl -s http://localhost:8080/document/v1/mynamespace/music/docid/2
    

12. Clean up:

    Once done with the VM, choose how to dispose of it. First exit the Vagrant SSH session:

    $ exit
    

    To continue working on the VM later, suspend it:

    $ vagrant suspend
    

    Then continue later by navigating to the sample-apps directory and launching the VM again with vagrant up

    To remove the VM and its resources, destroy it:

    $ vagrant destroy
    

Next steps