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.

  1. Get a sample application:

    $ git clone --depth 1 && \
      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:

    On Unix or Mac, use openssl:

    $ 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

    On Windows, the certificate has to be created with New-SelfSignedCertificate in PowerShell, and then exported to PEM format using certutil.

    Once the certificate has been created, add it to the application package.

    $ 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 . \
      -x "ext/*" .gitignore ".git/*"
 is the artifact to be deployed in next steps.

  4. Create a tenant in the Vespa Cloud:

    Create a tenant at (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

    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.default
    $ vespa config set target cloud
    $ vespa config set application vespa-team.album-rec-java
    $ export VESPA_CLI_API_KEY="$(echo "$VESPA_TEAM_API_KEY" | openssl base64 -A -a -d)"
    $ cp data-plane-public-cert.pem $VESPA_CLI_HOME/vespa-team.album-rec-java.default
    $ cp data-plane-private-key.pem $VESPA_CLI_HOME/vespa-team.album-rec-java.default
    $ vespa deploy --wait 600
    $ export ENDPOINT=
  6. Verify the application endpoint:

    $ 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" : "",
        "class" : "",
        "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 \
    $ 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 \
    $ 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 \

    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}"
      }' \
    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \

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

Next steps