Skip to content

News: Vespa cloud instead of local. HF dataset fix #4816

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BrageHK merged 3 commits into from
Aug 4, 2026
Merged

News: Vespa cloud instead of local. HF dataset fix #4816

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0434a87
News: Vespa cloud instead of local. HF dataset fix
BrageHK Aug 4, 2026
e6c5487
Update en/learn/tutorials/news-1-deploy-an-application.md
BrageHK Aug 4, 2026
6c60ddb
docs: explanation of why to use global meta-config
BrageHK Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 68 additions & 96 deletions en/learn/tutorials/news-1-deploy-an-application.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
# Copyright Vespa.ai. All rights reserved.
title: "News search and recommendation tutorial - getting started on Docker"
title: "News search and recommendation tutorial - getting started on Vespa Cloud"
redirect_from:
- /en/tutorials/news-1-getting-started.html
- /en/tutorials/news-1-deploy-an-application
---


Our goal with this series is to set up a Vespa application for personalized
news recommendations. We will do this in stages, starting with a simple news
news recommendations on Vespa Cloud. We will do this in stages, starting with a simple news
search system and gradually adding functionality as we go through the
tutorial parts.

Expand All @@ -22,32 +22,33 @@ The parts are:
6. [News recommendation with searchers](news-6-recommendation-with-searchers.html) - custom searchers, doc processors
7. [News recommendation with parent-child](news-7-recommendation-with-parent-child.html) - parent-child, tensor ranking

There are different entry points to this tutorial. This one is describing how to get
started using Docker on your local machine. You can also deploy the application we are creating on
[Vespa Cloud](https://cloud.vespa.ai).

In this part, we will start with a minimal Vespa application to
get used to some basic operations for running the application on Docker.
In this part, we will start with a minimal Vespa application to get used to some basic
operations for deploying and running an application on Vespa Cloud.
In the next part of the tutorial, we'll start developing our application.

{% include pre-req.html memory="4 GB" extra-reqs='
<li>Python3 for converting the dataset to Vespa JSON.</li>
<li><code>curl</code> to download the dataset and run the Vespa health-checks.</li>
<li><a href="https://openjdk.org/projects/jdk/17/" data-proofer-ignore>Java 17</a> in part 6.</li>
<li><a href="https://maven.apache.org/install.html">Apache Maven</a> in part 6.</li>' %}

{% include note.html content='4 GB Docker memory is sufficient for the demo dataset in part 2.
The <span style="text-decoration: underline;">full</span> MIND dataset requires more, use 10 GB.' %}
<div class="vespa-notification vespa-notification-prereqs" role="alert">
<p><strong>Prerequisites:</strong></p>
<ul>
<li>A Vespa Cloud account - create a <a href="https://console.vespa-cloud.com/">tenant</a>
if you do not have one.</li>
<li><a href="https://brew.sh/">Homebrew</a> to install the <a href="../../clients/vespa-cli.html">Vespa CLI</a>,
or download the Vespa CLI from <a href="https://github.com/vespa-engine/vespa/releases">Github releases</a>.</li>
<li>Python3 for converting the dataset to Vespa JSON.</li>
<li><code>curl</code> to download the dataset.</li>
<li><a href="https://openjdk.org/projects/jdk/17/" data-proofer-ignore>Java 17</a> in part 6.</li>
<li><a href="https://maven.apache.org/install.html">Apache Maven</a> in part 6.</li>
</ul>
</div>

In upcoming parts of this series, we will have some additional Python dependencies -
we use [PyTorch](https://pytorch.org/) to train vector representations for news and users
and train machine learning models for use in ranking.


## Installing vespa-cli
## Installing Vespa CLI

This tutorial uses [Vespa-CLI](../../clients/vespa-cli.html),
Vespa CLI is the official command-line client for Vespa.ai.
Vespa CLI is the official command-line client for Vespa.ai.
It is a single binary without any runtime dependencies and is available for Linux, macOS, and Windows.

<div class="pre-parent">
Expand All @@ -57,18 +58,23 @@ $ brew install vespa-cli
</pre>
</div>

For the rest of this tutorial, you will be using localhost, so you need to configure your Vespa CLI to connect to localhost.
Run the following to use endpoints on localhost:
In this tutorial it is possible to use either a local or global
Vespa CLI configuration mode for configuration variables. Using
local configuration mode is generally recommended when working
with multiple distinct Vespa applications, but most parts of
this tutorial uses the same configuration values which makes
it easier to use global configuration mode. The global
configuration mode is useful because you don't have to reapply
the same Vespa configurations for each part of this tutorial series:

<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre>
$ vespa config set target local
$ vespa config set default_config_scope global

@sebastiannberg sebastiannberg Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dont remember if global is already default? If it is then maybe we can instead switch to this section saying
vespa config set target cloud. For the sake of the tutorial it is kinda agnostic if they use global or local config scope, but target must be cloud

@sebastiannberg sebastiannberg Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see now further down we say set target cloud, so it might be worth considering just dropping the config scope section?

@sebastiannberg sebastiannberg Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh ok now it makes sense, since the tutorial follow multiple steps we set the config scope to global so we dont have to set it over and over again. Maybe add a short sentence about this already when we set it to global

</pre>
</div>



## A minimal Vespa application

This tutorial has a [companion sample application](https://github.com/vespa-engine/sample-apps/tree/master/news).
Expand Down Expand Up @@ -105,58 +111,69 @@ There are two files there:
We will revisit these files in the next part of the tutorial.


## Starting Vespa
## Configuring Vespa CLI for Vespa Cloud
Configure the Vespa CLI to use Vespa Cloud, and set the application name.
Replace `tenant-name` with your tenant name from [console.vespa-cloud.com](https://console.vespa-cloud.com):

This application doesn't contain much at the moment,
let's start up the application anyway by starting a Docker container to run it:
<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre>
$ vespa config set target cloud
$ vespa config set application tenant-name.news
</pre>
</div>

Usually its better to use local configuration for each application,
but this tutorial uses global configuration to avoid having to set the
configuration values for each part of the tutorial.

Authenticate with Vespa Cloud:

<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre data-test="exec">
$ docker pull vespaengine/vespa
$ docker run --detach --name vespa --hostname vespa-tutorial \
--publish 8080:8080 --publish 19071:19071 --publish 19092:19092 \
vespaengine/vespa
<pre>
$ vespa auth login
</pre>
</div>

First, we pull the latest [vespa-image](https://hub.docker.com/r/vespaengine/vespa/)
from the Docker hub, then we
start it with the name `vespa`. This starts the Docker container and the
initial Vespa services to be able to deploy an application.
Follow the browser instructions to complete authentication.

Starting the container can take a short while. Before continuing, make sure
that the configuration service is running by using `vespa status`.
Next, add a certificate for [data plane access](/en/security/guide#data-plane) to the application:

<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre data-test="exec">
$ vespa status deploy --wait 300
<pre>
$ vespa auth cert app-1-getting-started
</pre>
</div>

With the config server up and running, deploy the application using vespa-cli:



## Deploying to Vespa Cloud

This application doesn't contain much at the moment,
but let's deploy it to Vespa Cloud anyway to get used to the basic operations.
The first deployment may take a few minutes while nodes are provisioned:

<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre data-test="exec">
$ vespa deploy --wait 300 app-1-getting-started
$ vespa deploy --wait 600 app-1-getting-started
</pre>
</div>

The command uploads the application and verifies the content.
If anything is wrong with the application, this step will fail with a failure description;
Otherwise, this switches the application to a live status.
otherwise, this switches the application to a live status.

Whenever you have a new version of your application,
Whenever you have a new version of your application,
run the same command to deploy the application.
In most cases, there is no need to restart services.
Vespa takes care of reconfiguring the system.
If a restart of services is required in some rare case, however, the output will notify
which services need restart to make the change effective.

In the upcoming parts of the tutorials, we'll frequently deploy the
application changes in this manner.
In the upcoming parts of the tutorials, we'll frequently deploy the
application changes in this manner.


## Feeding to Vespa
Expand All @@ -167,7 +184,7 @@ For now, to test that everything is up and running, we'll feed in a single test
<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre data-test="exec" >
$ vespa feed -t http://localhost:8080 doc.json
$ vespa feed doc.json
</pre>
</div>

Expand Down Expand Up @@ -237,57 +254,12 @@ $ vespa document -v remove id:news:news::1
Well done!


## Stopping and starting Vespa

Keep Vespa running to continue with the next steps in this tutorial set (skip the below).
## Managing the Vespa Cloud application

To stop Vespa, we can run the following commands:

<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre>
$ docker exec vespa vespa-stop-services
$ docker exec vespa vespa-stop-configserver
</pre>
</div>

Likewise, to start the Vespa services:

<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre>
$ docker exec vespa vespa-start-configserver
$ docker exec vespa vespa-start-services
</pre>
</div>

If a [restart is required](../../reference/schemas/schemas.html#changes-that-require-restart-but-not-re-feed)
due to changes in the application package,
these two steps are what you need to do.

To wipe the index and restart:

<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre>
$ docker exec vespa sh -c ' \
vespa-stop-services && \
vespa-remove-index -force && \
vespa-start-services'
</pre>
</div>

You can stop and kill the Vespa container application like this:

<div class="pre-parent">
<button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre data-test="after">
$ docker stop vespa; docker rm -f vespa
</pre>
</div>
Application instances in the [dev zone](../operations/environments.html#dev) will by default keep running for 14 days after the last deployment.
You can control this in the [console](https://console.vespa-cloud.com/).

This will delete the Vespa application, including all data and configuration. See
[container tuning for production](../../operations/self-managed/docker-containers.html).
The [Vespa Cloud console](https://console.vespa-cloud.com) can also be used to delete the application instance.


## Conclusion
Expand Down
Loading