# Source: https://docs.vespa.ai/en/learn/tutorials/news-1-deploy-an-application.html.md

# News search and recommendation tutorial - getting started on Docker

 

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 search system and gradually adding functionality as we go through the tutorial parts.

The parts are:

1. [Getting started](news-1-deploy-an-application.html) - this part
2. [A basic news search application](news-2-basic-feeding-and-query.html) - application packages, feeding, query
3. [News search](news-3-searching.html) - sorting, grouping, and ranking
4. [Generating embeddings for users and news articles](news-4-embeddings.html)
5. [News recommendation](news-5-recommendation.html) - partial updates (news embeddings), ANNs, filtering
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 the next part of the tutorial, we'll start developing our application.

**Prerequisites:**

- Linux, macOS or Windows 10 Pro on x86\_64 or arm64, with [Podman Desktop](https://podman.io/) or [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed, with an engine running. 
  - Alternatively, start the Podman daemon:
```
$ podman machine init --memory 6000
$ podman machine start
```
  - See [Docker Containers](/en/operations/self-managed/docker-containers.html) for system limits and other settings.

- For CPUs older than Haswell (2013), see [CPU Support](/en/cpu-support.html).
- Memory: Minimum 4 GB RAM dedicated to Docker/Podman. [Memory recommendations](/en/operations/self-managed/node-setup.html#memory-settings). 
- Disk: Avoid `NO_SPACE` - the vespaengine/vespa container image + headroom for data requires disk space. [Read more](/en/writing/feed-block.html). 
- [Homebrew](https://brew.sh/) to install the [Vespa CLI](/en/clients/vespa-cli.html), or download the Vespa CLI from [Github releases](https://github.com/vespa-engine/vespa/releases). 
- Python3 for converting the dataset to Vespa JSON.
- `curl` to download the dataset and run the Vespa health-checks.
- [Java 17](https://openjdk.org/projects/jdk/17/) in part 6.
- [Apache Maven](https://maven.apache.org/install.html) in part 6.

 **Note:** 4 GB Docker memory is sufficient for the demo dataset in part 2. The full MIND dataset requires more, use 10 GB.

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

This tutorial uses [Vespa-CLI](../../clients/vespa-cli.html), 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.

```
$ brew install vespa-cli
```

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:

```
$ vespa config set target local
```

## A minimal Vespa application

This tutorial has a [companion sample application](https://github.com/vespa-engine/sample-apps/tree/master/news). Throughout the tutorial, we will be using support code from this application. Also, the final state of each tutorial can be found in the various `app-...` subdirectories.

Let's start by cloning the sample application:

```
$ vespa clone -f news news && cd news
```

The above downloads the `news` directory from the Vespa[sample apps repository](https://github.com/vespa-engine/sample-apps/) and places the contents in a folder called `news`. Use `--help` to see documentation for the vespa-cli utility:

```
$ vespa clone --help
```

In the `news` directory, several pre-configured application packages are available. The `app-1-getting-started` directory contains a minimal Vespa application. There are two files there:

- `services.xml` - defines the services that the application consists of
- `schemas/news.sd` - defines the schema for searchable content.

We will revisit these files in the next part of the tutorial.

## Starting Vespa

This application doesn't contain much at the moment, let's start up the application anyway by starting a Docker container to run it:

```
$ docker pull vespaengine/vespa
$ docker run --detach --name vespa --hostname vespa-tutorial \
  --publish 8080:8080 --publish 19071:19071 --publish 19092:19092 \
  vespaengine/vespa
```

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.

Starting the container can take a short while. Before continuing, make sure that the configuration service is running by using `vespa status`.

```
$ vespa status deploy --wait 300
```

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

```
$ vespa deploy --wait 300 app-1-getting-started
```

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.

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.

## Feeding to Vespa

We must index data before we can search for it. This is called "feeding", and we'll get back to that in more detail in the next part of the tutorial. For now, to test that everything is up and running, we'll feed in a single test document:

```
$ vespa feed -t http://localhost:8080 doc.json
```

The `-v` option will make vespa-cli print the http request:

```
$ vespa document -v doc.json
```

We can also feed using [Vespa document api](../../writing/document-v1-api-guide.html) directly.

Once the feed operation is acknowledged by Vespa, the operation is visible in search.

## Querying Vespa

We can query the endpoint using the vespa-cli's support for performing queries. It uses the [Vespa query api](../../querying/query-api.html) to query vespa, including `-v` in the command, we can see the exact endpoint and url request parameters used.

```
$ vespa query -v 'yql=select * from news where true'
```

This example uses [YQL (Vespa Query Language)](../../querying/query-language.html) to search for all documents of type `news`. This query request will return `1` result, which is the document we fed above.

```
$ vespa query \
  'yql=select * from news where userQuery()' \
  'query=hello world' \
  'default-index=title'
```

Another query language example that searches for hello or world in the title.

```
$ vespa query \
  'yql=select * from news where title contains phrase("hello","world")'
```

Another query language example that searches for the phrase "hello world" in the title. In the [next part of the tutorial](news-2-basic-feeding-and-query.html) we'll demonstrate more query examples, and also ranking and grouping of results.

## Remove documents

Run the following to remove the document from the index:

```
$ 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).

To stop Vespa, we can run the following commands:

```
$ docker exec vespa vespa-stop-services
$ docker exec vespa vespa-stop-configserver
```

Likewise, to start the Vespa services:

```
$ docker exec vespa vespa-start-configserver
$ docker exec vespa vespa-start-services
```

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:

```
$ docker exec vespa sh -c ' \
  vespa-stop-services && \
  vespa-remove-index -force && \
  vespa-start-services'
```

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

```
$ docker stop vespa; docker rm -f vespa
```

This will delete the Vespa application, including all data and configuration. See [container tuning for production](../../operations/self-managed/docker-containers.html).

## Conclusion

Our simple application should now be up and running. In the [next part of the tutorial](news-2-basic-feeding-and-query.html), we'll start building from this foundation.

 Copyright © 2026 - [Cookie Preferences](#)

### On this page:

- [Installing vespa-cli](#installing-vespa-cli)
- [A minimal Vespa application](#a-minimal-vespa-application)
- [Starting Vespa](#starting-vespa)
- [Feeding to Vespa](#feeding-to-vespa)
- [Querying Vespa](#querying-vespa)
- [Remove documents](#remove-documents)
- [Stopping and starting Vespa](#stopping-and-starting-vespa)
- [Conclusion](#conclusion)