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 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:

   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 application.zip . \
     -x application.zip "ext/*" README.md .gitignore ".git/*"
   

   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.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=https://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

• Set up deployment to production.
• Try a version of this application with Java components.
• Learn more about Vespa in the Vespa documentation.
• Follow the Vespa Blog for product updates and use cases.