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/basic-search
    $ 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/basic-search/music-data-1.json \
        http://localhost:8080/document/v1/music/music/docid/1 | python -m json.tool
    
    $ curl -s -H "Content-Type:application/json" --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 single document API. Use the http client to feed large amounts of data fast.

  10. <
  11. Run a query post or get request :
    $ curl -s -H "Content-Type: application/json" --data '{"query" : "bad"}' http://localhost:8080/search/ | python -m json.tool
    
    $ curl -s http://localhost:8080/search/?query=bad | python -m json.tool
    
    View the results in a browser in the GUI for building queries at http://localhost:8080/querybuilder/, which can help you building queries with e.g. autocompletion of YQL, or at http://localhost:8080/search/?query=bad. Read more in the Search API.
  12. Run a document get request :
    $ curl -s http://localhost:8080/document/v1/music/music/docid/2 | python -m json.tool
    
  13. Clean up when you're done

    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

If you encounter any problems see troubleshooting.

Next Steps