Getting Started (without Vespa CLI)

Follow these steps to deploy an application to the dev zone in the Vespa Cloud. Find more details and tips in the developer guide, and see next steps for self-hosted deployment options. Alternative versions of this guide:

• Getting started, with Vespa CLI
• Getting started, with an app having Java components
• Getting started, using pyvespa - for Python developers
• Run Vespa locally, using Docker.

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 other sample apps you can start from instead.

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. 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.
• Follow the Vespa Blog for product updates and use cases.
• Explore the Vespa documentation.