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 -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 single document API. Use the http client to feed large amounts of data fast.

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

    You can also view the results in a browser at http://localhost:8080/search/?query=bad. Read more in the Search API.

  11. 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
    

Next Steps