• [+] expand all

Getting Started
edit page

Welcome to Vespa! Following is a list of resources for first time users - Vespa can do many things, and be deployed in many ways. Let us know if something is missing.

Minimal Quick Start Install Vespa, insert a few documents and run a query, using Docker or Vagrant: For Vespa Cloud users, see Getting Started.
Monitoring Quick Start Try the Monitoring Quick Start - it builds on the Minimal Quick Start, and adds more features that most applications normally use:
  • Monitoring using a Grafana dashboard
  • High-performance feeding API
  • A document and query simulator - to validate the dashboard, but also something to build on for own application development
Plugin Development

Vespa supports writing plugins in languages that runs in the JVM. Use this to simplify Query and Document processing:

Vespa Plugins has more details.

For Vespa Cloud users, also see Getting Started Custom Code.

Deployments

Vespa is an open source platform and can be deployed in multiple ways - explore:

These guides are good starters for building clusters of more than one node.

Also try deploying to Vespa Cloud, a managed service running Vespa.

Jupyter Notebooks

This is under active development, check back for more pointers later:

Tutorials and use cases

Run the tutorials to learn how Vespa can be used in search and recommender applications:

Try the e-commerce shopping use case.

Next Steps

Troubleshooting

Also see the FAQ.

No endpoint Most problems with the quick start guides are due to Docker out of memory. Make sure at least 6G memory is allocated to Docker: 
$ docker info | grep "Total Memory"
OOM symptoms include 
INFO: Problem with Handshake localhost:8080 ssl=false: localhost:8080 failed to respond
The container is named vespa in the guides, for a shell do: 
$ docker exec -it vespa bash
Log viewing Use vespa-logfmt to view the vespa log - example: 
$ /opt/vespa/bin/vespa-logfmt -l warning,error
Json For json pretty-print, append 
| python -m json.tool
to commands that output json - or use jq.

Vespa Cloud deployments

Slow deployments: First time deployments takes a few minutes, seeing CERTIFICATE_NOT_READY / PARENT_HOST_NOT_READY / LOAD_BALANCER_NOT_READY is normal. "Installation succeeded!" in the bottom pane indicates success
HTTP: 502 — Bad Gateway: This means the endpoint is not ready, or failing. A Vespa software upgrade will cause this — the application will then be unavailable for 15 minutes or so, as dev instances are not redundant. Look for stopping services in logs to check for this.
Retrying — request failed: Java heap space: If this happens when deploying from the laptop, mvn runs out of memory. Use export MAVEN_OPTS=-Xmx3g to increase the heap size to 3G (or larger as needed).

Plugin Development

Cannot find *Config classes

Several projects depend on generated configuration classes. These are created by the generate-sources Maven target. The easiest way to avoid the problem is building the project with Maven from the shell, then importing in Eclipse/IntelliJ. If the project is already imported, first run the generate-sources target either from the IDE or the shell, then mark the pertinent target/generated-sources/vespa-configgen-plugin directories as source directories.

Maven

On error: 

  at org.codehaus.plexus.archiver.AbstractArchiver$1.hasNext(AbstractArchiver.java:482)
increase the maven thread stack size by export MAVEN_OPTS=-Xss2m

Running on Linux

IntelliJ does not pick up custom test profiles from pom.xml. If running IntelliJ on a Linux, configure its test environment with a reference to the library path (i.e. $VESPA_ROOT/lib64). The simplest way to do this is to edit the default configuration for JUnit.

Ignored provider

This it is usually a packaging problem: 

A provider [the class] registered in SERVER runtime does not implement any provider interfaces
applicable in the SERVER runtime.
Due to constraint configuration problems the provider [the class] will be ignored.
The JAX-RS classes, like the @GET annotation, have been bundled inside the plug-in bundle, causing the container not to recognize them as valid annotations. The fix is using mvn dependency:tree to figure out what dependency has caused JAX-RS to be included, and then add the proper exclusion clause to pom.xml.

No result returned when throwing WebApplicationException

The container has no special handling of javax.ws.rs.WebApplicationException and its subclasses. All Jersey plug-ins must either be exception safe, or supply the proper implementations of javax.ws.rs.ext.ExceptionMapper for all exceptions which are expected to be thrown from the plug-in (and annotate these with @Provider).