Skip to content
Branch: master
Find file History
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Revert "Revert "Kkraune/remove redundant app"" Jan 23, 2020
.gitignore ignore Nov 29, 2019 Fix some links, and remove unnecessary arguments in sample command Feb 21, 2020
pom.xml Remove key properties from pom.xml Feb 19, 2020

Vespa sample applications - album recommendations java

Extends the album-recommendations sample application with a Searcher component in Java which does query and result processing. Refer to developing searchers for more information.

This sample app introduces how to write system tests and how to integrate with a CI/CD pipeline.

See getting started for troubleshooting.

Security notes:

  • To deploy to your instance, a personal API key is required. See step 4 below.
  • To read and write to the instance's endpoint, a certificate and a private key is required. See step 2 below. Find more details in Data Plane, see Client certificate.
  • Instead of using a personal API key, one can also deploy using the console, see step 5 in album-recommendation.

Getting started

Prerequisites: git, Java 11, mvn 3.6.1 and openssl.

  1. Download sample apps:

    $ git clone && cd sample-apps/album-recommendation-java
  2. Get a X.509 certificate and private key. Create a self-signed certificate / private key:

    $ openssl req -x509 -nodes -days 14 -newkey rsa:4096 \
    -subj "/C=NO/ST=Trondheim/L=Trondheim/O=My Company/OU=My Department/" \
    -keyout data-plane-private-key.pem -out data-plane-public-cert.pem
  3. Add certificate to application package (it must be copied as clients.pem):

    $ mkdir -p src/main/application/security && cp data-plane-public-cert.pem src/main/application/security/clients.pem
  4. Go to, choose tenant and click Keys to generate and save the personal API key. The key is saved to $HOME/Downloads/TENANTNAME.pem. Then click "Create application"

  5. Edit the properties tenant and application in pom.xml — use the values entered in the console in 4.

  6. Build the app:

    $ mvn clean package
  7. Deploy the application to the dev environment and wait for it to start - update the apiKeyFile to be the file you downloaded above:

    $ mvn vespa:deploy -DapiKeyFile=$HOME/Downloads/TENANTNAME.pem
  8. Now is a good time to read, as first time deployments takes a few minutes. Seeing CERTIFICATE_NOT_READY / PARENT_HOST_NOT_READY / LOAD_BALANCER_NOT_READY is normal. The endpoint URL is printed in the Install application section when the deployment is successful - copy this for the next step.

  9. Store the endpoint of the application:


    Try the endpoint:

    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem $ENDPOINT
  10. Feed documents:

    $ 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 \
    $ 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 \
    $ 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 \
  11. Visit documents:

    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
  12. Recommend albums, send user profile in query:

    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \

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

    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
  13. At this point, the application is built, unit tested, deployed to a dev instance, fed to and a few test queries have been run. Safe deployments depends on automated testing. Vespa Cloud has support for running system and staging tests for every change to an application. These tests are run as JUnit tests, but use the endpoints of a real deployment of the application. When submitting an application to Vespa Cloud, a test instance is set up and tests automatically run using its endpoints. To develop system and staging tests, deploy the application to dev (like above) and run tests like FeedAndSearchSystemTest:

    $ mvn test -Dtest.categories=system \
      -DdataPlaneKeyFile=data-plane-private-key.pem \
      -DdataPlaneCertificateFile=data-plane-public-cert.pem \

    or run it directly from an IDE. must have access to the data plane key and certificate pair, to talk to the application endpoint.

    Find more details in the Vespa Cloud API and automated-deployments.

  14. To run tests against a deployment running in Docker on localhost (instead of using dev), configure endpoint location:

        "localEndpoints": {
        "container": "http://localhost:8080/"

    in some file /path/to/test/config, and run JUnit tests with -Dvespa.test.config=/path/to/test/config -Dtest.categories=system. Refer to album-recommendation-selfhosted for how to create the application package.

  15. When System and Staging tests are ready, deploy to production. Command to build and submit application to the hosted Vespa API is

    mvn clean vespa:compileVersion -DapiKeyFile=$HOME/Downloads/TENANTNAME.pem
    mvn -P fat-test-application \
    -Dvespaversion="$(cat target/vespa.compile.version)" \
    -DapiKeyFile=$HOME/Downloads/TENANTNAME.pem \
    package vespa:submit
You can’t perform that action at this time.