Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
162 lines (143 sloc) 6.73 KB
---
# Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
title: "Quick Start"
---
<p>
This guide describes how to install and run Vespa on a single machine using Docker. Once you have completed
the steps in this guide, you have a running Vespa instance with searchable documents in it and will have run
some search queries against them.</p>
<p>Also try the <a href="vespa-quick-start-centos.html">CentOS / Vagrant</a> or
<a href="vespa-quick-start-windows.html">Windows</a> guide.
</p><p>
<strong>Prerequisites</strong>:
<ul>
<li><a href="https://docs.docker.com/engine/installation/">Docker</a> installed.</li>
<li><a href="https://git-scm.com/downloads">Git</a> installed.</li>
<li>Operating system: macOS or Linux</li>
<li>Architecture: x86_64</li>
<li><b>Minimum 6GB</b> memory dedicated to Docker (the default is 2GB on Macs).</li>
</ul>
This guide is tested with Docker for Mac, Community Edition-18.06.1-ce-mac73 (26764) and
<em>vespaengine/vespa</em> Docker image built 2018-10-01.
</p>
<h2>Running Vespa in Docker</h2>
<ol>
<li>
<p><strong>Clone the Vespa sample apps from
<a href="https://github.com/vespa-engine/sample-apps">github</a>:</strong></p>
<pre data-test="exec">
$ git clone https://github.com/vespa-engine/sample-apps.git
$ export VESPA_SAMPLE_APPS=`pwd`/sample-apps
</pre>
</li>
<li>
<p><strong>Start a Vespa Docker container:</strong></p>
<pre data-test="exec">
$ docker run --detach --name vespa --hostname vespa-container --privileged \
--volume $VESPA_SAMPLE_APPS:/vespa-sample-apps --publish 8080:8080 vespaengine/vespa
</pre>
<p>
The <samp>volume</samp> option makes the previously downloaded source code available
as <samp>/vespa-sample-apps</samp> inside the docker container.
The port <samp>8080</samp> is published to make the search and feed interfaces
accessible outside of the docker container.
Only one docker container named <samp>vespa</samp> can run at a time so change the name if needed.
</p>
<p>
If you're interested in the exact steps performed by the above command, please see the
<a href="https://github.com/vespa-engine/docker-image/blob/master/Dockerfile">Dockerfile</a> and
the <a href="https://github.com/vespa-engine/docker-image/blob/master/include/start-container.sh">startup script</a>.
</p>
</li>
<li>
<p><strong>Wait for the configuration server to start - signified by a 200 OK response:</strong></p>
<pre data-test="exec" data-test-wait-for="200 OK">
$ docker exec vespa bash -c 'curl -s --head http://localhost:19071/ApplicationStatus'
</pre>
</li>
<li>
<p><strong>Deploy and activate a sample application:</strong></p>
<pre data-test="exec">
$ docker exec vespa bash -c '/opt/vespa/bin/vespa-deploy prepare /vespa-sample-apps/basic-search/src/main/application/ &amp;&amp; \
/opt/vespa/bin/vespa-deploy activate'
</pre>
<p>More sample applications can be found in
<a href="https://github.com/vespa-engine/sample-apps/tree/master">sample-apps</a>.
Read more on applications in
<a href="cloudconfig/application-packages.html">Application packages</a>.</p>
</li>
<li>
<p><strong>Ensure the application is active - wait for a 200 OK response:</strong></p>
<pre data-test="exec" data-test-wait-for="200 OK">
$ curl -s --head http://localhost:8080/ApplicationStatus
</pre>
</li>
<li>
<p><strong>Feed documents into Vespa:</strong></p>
<pre data-test="exec">
$ curl -s -H "Content-Type:application/json" --data-binary @${VESPA_SAMPLE_APPS}/basic-search/music-data-1.json \
http://localhost:8080/document/v1/music/music/docid/1 | python -m json.tool
$ curl -s -H "Content-Type:application/json" --data-binary @${VESPA_SAMPLE_APPS}/basic-search/music-data-2.json \
http://localhost:8080/document/v1/music/music/docid/2 | python -m json.tool
</pre>
<p>This uses the <a href="document-api.html">document API</a>.
Use the <a href="vespa-http-client.html">Vespa HTTP client</a> to feed large amounts of data fast.</p>
</li>
<li>
<p><strong>Make a query POST or GET request:</strong></p>
<pre data-test="exec" data-test-assert-contains="Michael Jackson">
$ curl -s -H "Content-Type: application/json" --data '{"query" : "bad"}' http://localhost:8080/search/ | python -m json.tool
</pre>
<pre data-test="exec" data-test-assert-contains="Michael Jackson">
$ curl -s http://localhost:8080/search/?query=bad | python -m json.tool
</pre>
<p>
You can also view query results in a browser with the query builder UI at <a href="http://localhost:8080/querybuilder/">http://localhost:8080/querybuilder/</a>, or have a look at raw query results at <a href="http://localhost:8080/search/?query=bad">http://localhost:8080/search/?query=bad</a>. The query builder can be used to develop search queries as it offers guided queries and YQL autocompletion.
</p>
<p>Read more in the <a href="search-api.html">Search API</a>.</p>
</li>
<li>
<p><strong>Run a document GET request:</strong></p>
<pre data-test="exec" data-test-assert-contains="Eminem">
$ curl -s http://localhost:8080/document/v1/music/music/docid/2 | python -m json.tool
</pre>
</li>
<li>
<p><strong><em>Optional:</em> Clean up when you're done</strong></p>
<p>Stop the running container when you no longer need it:</p>
<pre data-test="after">
$ docker stop vespa
</pre>
<p>You can then also remove the stopped container entirely:</p>
<pre data-test="after">
$ docker rm vespa
</pre>
</li>
</ol>
<h2 id="troubleshooting">Troubleshooting</h2>
<p>If you encounter any problems see <a href="vespa-quick-start-troubleshooting.html">troubleshooting</a>.</p>
<h2 id="next-steps">Next Steps</h2>
<ul>
<li>
This application is fully functional and production ready, but you may want to
<a href="multinode-systems.html">add more nodes</a> for redundancy.
</li><li>
Try the <a href="tutorials/blog-search.html">Blog search and recommendation tutorial</a>
to learn more about using Vespa
</li><li>
See <a href="jdisc/developing-applications.html">developing applications</a>
on adding your own Java components to your Vespa application.
</li><li>
<a href="api.html">Vespa APIs</a> is useful to understand how to interface with Vespa
</li><li>
Explore the <a href="https://github.com/vespa-engine/sample-apps/tree/master">
sample applications</a>
</li><li>
How to <a href="securing-your-vespa-installation.html">secure a Vespa installation</a>
</li><li>
To run on AWS, see the <a href="vespa-quick-start-multinode-aws.html">AWS EC2 multinode quick start</a>
or <a href="vespa-quick-start-multinode-aws-ecs.html">AWS ECS multinode quick start</a>
</li><li>
To run on Docker Swarm, see this <a href="https://github.com/vespa-engine/sample-apps/tree/master/basic-search-on-docker-swarm">example application.</a>
</li>
</ul>