Getting Started with the Vespa Cloud

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

There is also a version on this that requires Maven and Java if you plan to add Java components to your application.

Prerequisites: Git, OpenSSL, zip and curl.


  1. Get a sample application:

    $ git clone --depth 1 https://github.com/vespa-engine/sample-apps.git && \
      cd sample-apps/album-recommendation
    

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

  2. Create a self-signed certificate:

    $ 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 security && \
      cp data-plane-public-cert.pem security/clients.pem
    

    This certificate and key will be used to send requests to Vespa Cloud. See the security model for more details.

  3. Create the application package:

    $ zip -r ../application.zip . -x "ext/*" README.md .gitignore ./*.pem
    

    application.zip is the artifact to be deployed in next steps.

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

  5. Create and deploy the application:

    Click Create Application. Use "myapp" as application name, leave the defaults. Make sure Dev is selected, and upload application.zip.

    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.

    $ export VESPA_CLI_HOME=$PWD/.vespa TMPDIR=$PWD/.tmp
    $ mkdir -p $TMPDIR
    $ mkdir -p $VESPA_CLI_HOME/vespa-team.album-rec-java.my-instance
    $ vespa config set target cloud
    $ vespa config set application vespa-team.album-rec-java.my-instance
    $ export VESPA_CLI_API_KEY="$(echo "$VESPA_TEAM_API_KEY" | openssl base64 -A -a -d)"
    $ mv ../application.zip .
    $ cp data-plane-public-cert.pem $VESPA_CLI_HOME/vespa-team.album-rec-java.my-instance
    $ cp data-plane-private-key.pem $VESPA_CLI_HOME/vespa-team.album-rec-java.my-instance
    $ vespa deploy --wait 600
    $ export ENDPOINT=https://my-instance.album-rec-java.vespa-team.aws-us-east-1c.dev.z.vespa-app.cloud/
    
  6. Verify the application endpoint:

    $ ENDPOINT=https://name.myapp.tenant-name.aws-us-east-1c.dev.z.vespa-app.cloud/
    
    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem $ENDPOINT
    

    Find the endpoint in the console output, set it for later use and test it. You can also do this in a browser. Sample output:

    {
      "handlers" : [ {
        "id" : "com.yahoo.search.handler.SearchHandler",
        "class" : "com.yahoo.search.handler.SearchHandler",
        "bundle" : "container-search-and-docproc:8.57.18",
        "serverBindings" : [ "http://*/search/*" ]
      }
      ...
    
  7. Write documents:

    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
      -H "Content-Type:application/json" \
      --data-binary @ext/A-Head-Full-of-Dreams.json \
      $ENDPOINT/document/v1/mynamespace/music/docid/a-head-full-of-dreams
    
    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
      -H "Content-Type:application/json" \
      --data-binary @ext/Love-Is-Here-To-Stay.json \
      $ENDPOINT/document/v1/mynamespace/music/docid/love-is-here-to-stay
    
    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
      -H "Content-Type:application/json" \
      --data-binary @ext/Hardwired...To-Self-Destruct.json \
      $ENDPOINT/document/v1/mynamespace/music/docid/hardwired-to-self-destruct
    

    This writes documents using /document/v1.

  8. Send queries:

    curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
      -X POST -H "Content-Type: application/json" --data '
      {
          "yql": "select * from music where true",
          "ranking": {
              "profile": "rank_albums",
              "features": {
                  "query(user_profile)": "{{cat:pop}:0.8,{cat:rock}:0.2,{cat:jazz}:0.1}"
              }
          }
      }' \
      $ENDPOINT/search/
    
    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
    "$ENDPOINT/search/?ranking=rank_albums&yql=select%20%2A%20from%20music%20where%20true&ranking.features.query(user_profile)=%7B%7Bcat%3Apop%7D%3A0.8%2C%7Bcat%3Arock%7D%3A0.2%2C%7Bcat%3Ajazz%7D%3A0.1%7D"
    

    Query with a user profile to get album recommendations using the Query API.

Next steps