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: git, openssl, JDK 11 or higher, mvn 3.6 or higher.

  1. Create an application in the Vespa Cloud

    Log in to console.vespa.ai and click "Create application".

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

  2. Make a local application source

    To start with the album-recommendation-searcher sample app:

    $ git clone --depth 1 https://github.com/vespa-engine/sample-apps.git
    $ cd sample-apps/vespa-cloud/album-recommendation-searcher
    
  3. Create a self-signed certificate

    This certificate and key will be used to send requests to Vespa Cloud later.

    $ openssl req -x509 -nodes -days 14 -newkey rsa:4096 \
      -subj "/CN=cloud.vespa.example" \
      -keyout data-plane-private-key.pem -out data-plane-public-cert.pem
    $ mkdir -p src/main/application/security
    $ cp data-plane-public-cert.pem src/main/application/security/clients.pem
    

    See the security model for more details.

  4. Create a deployment API key

    In the console console.vespa.ai, choose tenant and click Keys to generate and save the user API key. The key is saved to $HOME/Downloads/USER.TENANTNAME.pem.

  5. Set the tenant and application name in the source

    Update pom.xml with the tenant and application names you chose when creating the application in the console.

  6. Build and deploy the application

    This deploys an instance (with a name you choose here) of the application to the dev zone:

    $ mvn package vespa:deploy -DapiKeyFile=$HOME/Downloads/USER.TENANTNAME.pem -Dinstance=my-instance
    
    $ API_KEY=`echo $VESPA_TEAM_API_KEY | openssl base64 -A -a -d`
    $ mvn clean package vespa:deploy -DapiKey="$API_KEY" -Dinstance=my-instance
    

    The first deployment may take a few minutes.

  7. Verify that you can reach the application endpoint

    The endpoint URL is printed in the Install application section when the deployment is successful. Put this in an environment variable and verify it.

    $ ENDPOINT=https://my-instance.album-rec-searcher.vespa-team.aws-us-east-1c.dev.public.vespa.oath.cloud
    $ curl --cert ./data-plane-public-cert.pem --key ./data-plane-private-key.pem $ENDPOINT
    

    You can also do this in a browser.

  8. Write some data

    Write three documents using the document api:

    $ curl --cert ./data-plane-public-cert.pem --key ./data-plane-private-key.pem \
      -H "Content-Type:application/json" --data-binary @src/test/resources/A-Head-Full-of-Dreams.json \
      $ENDPOINT/document/v1/mynamespace/music/docid/1
    $ curl --cert ./data-plane-public-cert.pem --key ./data-plane-private-key.pem \
      -H "Content-Type:application/json" --data-binary @src/test/resources/Love-Is-Here-To-Stay.json \
      $ENDPOINT/document/v1/mynamespace/music/docid/2
    $ curl --cert ./data-plane-public-cert.pem --key ./data-plane-private-key.pem \
      -H "Content-Type:application/json" --data-binary @src/test/resources/Hardwired...To-Self-Destruct.json \
      $ENDPOINT/document/v1/mynamespace/music/docid/3
    
  9. Send queries

    Send a user profile as a query to get album recommendations:

    $ curl --cert ./data-plane-public-cert.pem --key ./data-plane-private-key.pem \
    "$ENDPOINT/search/?ranking=rank_albums&yql=select%20%2A%20from%20sources%20%2A%20where%20sddocname%20contains%20%22music%22%3B&ranking.features.query(user_profile)=%7B%7Bcat%3Apop%7D%3A0.8%2C%7Bcat%3Arock%7D%3A0.2%2C%7Bcat%3Ajazz%7D%3A0.1%7D"
    

    A few more examples:

    Limit to albums with the term "to" in title:

    $ curl --cert ./data-plane-public-cert.pem --key ./data-plane-private-key.pem \
      "$ENDPOINT/search/?ranking=rank_albums&yql=select%20%2A%20from%20sources%20%2A%20where%20album%20contains%20%22to%22%3B&ranking.features.query(user_profile)=%7B%7Bcat%3Apop%7D%3A0.8%2C%7Bcat%3Arock%7D%3A0.2%2C%7Bcat%3Ajazz%7D%3A0.1%7D"
    

    Retrieve all document using visit:

    $ curl --cert ./data-plane-public-cert.pem --key ./data-plane-private-key.pem \
      "$ENDPOINT/document/v1/mynamespace/music/docid?wantedDocumentCount=100"
    

Next steps