Getting started, including Java development

Follow these steps to deploy your first application to the dev zone in the Vespa Cloud. Find more details and tips in the developer guide.

There is also a version of this guide that does not require Maven and Java.

Prerequisites: JDK 11+ and Maven 3.6+.

  1. Install the Vespa CLI

    Using Homebrew:

    $ brew install vespa-cli

    You can also download Vespa CLI for Windows, Linux and macOS.

  2. Create your tenant in the Vespa Cloud

    If you don't already have a Vespa Cloud tenant, create one at This requires a Google or GitHub account, and will start your free trial.

  3. Initialize myapp/ to a copy of a sample application package (see sample-apps):

    $ vespa clone album-recommendation-java myapp && cd myapp
  4. Let pom.xml specify the right tenant and application name.

    Set tenant and application under properties in pom.xml to the tenant name registered in the console, and a suitable application name ("myapp").

  5. Tell the Vespa CLI to use Vespa Cloud, with your application

    $ vespa config set target cloud && \
      vespa config set application <tenant-name>.myapp.default
    $ export VESPA_CLI_HOME=$PWD/.vespa TMPDIR=$PWD/.tmp
    $ mkdir -p $TMPDIR
    $ vespa config set target cloud
    $ vespa config set application

    Use the tenant and application name from the previous step.

  6. Authorize access to Vespa Cloud

    $ vespa auth login
    $ export VESPA_CLI_API_KEY="$(echo "$VESPA_TEAM_API_KEY" | openssl base64 -A -a -d)"

    Follow the instructions from the command to authenticate.

  7. Create a self-signed certificate for accessing your application:

    $ vespa auth cert

    See the security model for more details.

  8. Build the application

    $ mvn -U package
  9. Deploy and verify that you can reach your application endpoint

    $ vespa deploy --wait 600

    The first deployment may take a few minutes.

  10. Feed documents:

    $ vespa document src/test/resources/A-Head-Full-of-Dreams.json && \
      vespa document src/test/resources/Love-Is-Here-To-Stay.json && \
      vespa document src/test/resources/Hardwired...To-Self-Destruct.json

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

  11. Issue queries:

    $ vespa query "select * from music where album contains 'head';"
    $ vespa query \
        "select * from music where true;" \
        "ranking=rank_albums" \

    This uses the Query API.

Next steps