Getting started, including Java development

Follow these steps to deploy your first application to the dev zone in the Vespa Cloud.

There is also a version on this 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:

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

    Set the properties tenant and application properties in pom.xml to your tenant and 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 step 2.

  6. Create a user API key

    $ vespa api-key
    $ echo "$VESPA_TEAM_API_KEY" | openssl base64 -A -a -d | openssl ec > $VESPA_CLI_HOME/vespa-team.api-key.pem

    Follow the instructions from the command to register the key.

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

    $ vespa cert

    See the security model for more details.

  8. Build and deploy the application

    $ mvn package vespa:deploy
    $ mvn package vespa:deploy -Dinstance=my-instance -DapiKeyFile=$VESPA_CLI_HOME/vespa-team.api-key.pem

    The first deployment may take a few minutes.

  9. Verify that you can reach your application endpoint

    $ vespa status --wait 300
  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 sources * where sddocname contains 'music';" "ranking=rank_albums" "ranking.features.query(user_profile)={{cat:pop}:0.8,{cat:rock}:0.2,{cat:jazz}:0.1}"

    This uses the Query API.

Next steps