Vespa quick start using VirtualBox and Vagrant

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

Prerequisites:

  1. Clone sample-apps repository

    $ 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. Ensure the configuration server is active:
    Wait for a 200 OK response from:
    $ 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 from:
    $ 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 the single document API. Use the 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 http://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 you're done with the VM you can choose how to dispose of it. First exit the Vagrant SSH session

    $ exit
    

    If you want 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

    If you want to remove the VM and its resources from your system, destroy it:

    $ vagrant destroy
    

Troubleshooting

See troubleshooting.

Next Steps