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 17+ and Maven 3.6+.


  1. Install the Vespa client:

    Using Homebrew:

    $ brew install vespa-cli
    

    Alternatively, download it for Windows, Linux and macOS.

  2. Create a tenant in the Vespa Cloud:

    Create a tenant at console.vespa-cloud.com (unless you already have one). This requires a Google or GitHub account, and will start your free trial. Make note of the tenant name, it is used in the next steps.

  3. Configure the Vespa client:

    $ 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 vespa-team.album-rec-java.my-instance
    

    Use the tenant name from step 2. This guide uses myapp as application name and default as instance name - learn more.

  4. Authorize Vespa Cloud access:

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

  5. Get a sample application:

    $ vespa clone album-recommendation-java myapp && cd myapp
    

    An application package is the full application configuration. See sample-apps for a full list.

  6. Add public certificate:

    $ vespa auth cert
    

    This creates a self-signed certificate for application data plane access (reads and writes), and adds it to the application package files. See the security model for more details.

  7. Build the application:

    $ mvn -U package
    
  8. Deploy the application:

    $ vespa deploy --wait 600
    

    The first deployment will take a few minutes while nodes are provisioned - track progress using the link in the response. Subsequent deployments on existing nodes will be quicker.

  9. 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 - read more about feeding.

  10. Run queries:

    $ vespa query "select * from music where album contains 'head'"
    
    $ vespa query \
        "select * from music where true" \
        "ranking=rank_albums" \
        "ranking.features.query(user_profile)={{cat:pop}:0.8,{cat:rock}:0.2,{cat:jazz}:0.1}"
    

    These requests use the Query API.

Next steps