Start the database, Voyager, and the application

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

In this step you start a local Aerospike Database, connect Aerospike Voyager to it, and launch the Spring Boot retail application that you implement throughout the rest of this tutorial. By the end of this step you have all three processes running and you can confirm, using both the Spring Boot logs and Voyager, that the database is reachable but that the application’s data-access methods do not yet write to the database.

This step assumes you have completed the tutorial prerequisites: Docker, JDK 21, Maven, and Voyager are installed, and the workshop repository is cloned.

Start the local Aerospike Database

The sample application’s docker-compose.yml starts a single-node Aerospike Database in a container named aerospike-workshop and exposes the client port on localhost:3000.

From the aerospike-client-sdk-workshop repository root, start the database in detached mode.
Terminal window
```
docker compose up -d
```
```
[+] Running 3/3
 ✔ Network aerospike-client-sdk-workshop_default          Created    0.0s
 ✔ Volume "aerospike-client-sdk-workshop_aerospike-data"  Created    0.0s
 ✔ Container aerospike-workshop                           Started    0.2s
```
Example response
Docker Compose redraws the progress block several times while it brings the network, volume, and container up. The final block, with Started next to aerospike-workshop, indicates that startup succeeded.

On older Docker installs the command is docker-compose up -d (with a hyphen) instead of docker compose up -d.

Confirm the container is running and reports a healthy status.

docker ps --filter name=aerospike-workshop

CONTAINER ID   IMAGE                                STATUS                    PORTS                              NAMES
c9318d9eb3e3   aerospike/aerospike-server:latest    Up 10 seconds (healthy)   0.0.0.0:3000-3003->3000-3003/tcp   aerospike-workshop

Example response

The container reports Up with a (healthy) annotation and exposes ports 3000 to 3003. If the container is not present, run docker compose logs aerospike-workshop to see why startup failed.

Launch Voyager and connect to the cluster

Voyager opens with three columns: a left-hand toolbar that switches between data, cluster management, MCP, and settings views; a middle column that lists known clusters; and a right-hand column that shows details for the selected cluster.

Launch Voyager.
In the cluster list (middle column), select Connect cluster.
Enter the connection details for the local Docker cluster.

The Docker container starts with security and TLS disabled, so the only fields you need to set are the cluster name, seed host, and port. Use the values shown in the Connect cluster dialog:

Field Value
Name Retail Demo (or any name you prefer)
Host localhost
Port 3000
TLS Off
Username / Password Leave blank
Select the Connect button.

The new cluster appears in the cluster list with a green status indicator.

Connecting without TLS or credentials is appropriate for a local development cluster only. Do not use these settings for any non-local cluster.
Select the cluster in the cluster list to open it.

Voyager opens a tab named after the cluster and shows one namespace named test in the right-hand panel.

The test namespace card reports 0 SETS and 0 records because no data has been written to the database yet.

Field	Value
Name	`Retail Demo` (or any name you prefer)
Host	`localhost`
Port	`3000`
TLS	Off
Username / Password	Leave blank

Run the Spring Boot application

The Spring Boot application uses the new-client Maven profile, which selects the implementation class you edit in later steps (KeyValueServiceNewClient). The application listens on port 8080, creates five secondary indexes, and auto-loads 200 records from the data/ folder.

Change into the spring-server directory.
Terminal window
```
cd spring-server
```

Build the application, skipping tests.

mvn clean package -DskipTests

[INFO] Scanning for projects...
[INFO] Building Retail Demo Showing off the Aerospike Javak SDK 1.0.0
[INFO] BUILD SUCCESS

Example response

Run the application with the new-client profile.

mvn spring-boot:run -Dspring-boot.run.profiles=new-client

The application logs include several lines that confirm a successful startup:

: Tomcat started on port 8080 (http) with context path '/'
: Started RetailDemoApplication in N seconds (process running for N)
: Created secondary index: article_idx on bin articleType
: Created secondary index: subCat_idx on bin subCategory
: Created secondary index: brand_idx on bin brandName
: Created secondary index: usage_idx on bin usage
: Created secondary index: cat_idx on bin category
: Auto-loading sample data from /.../aerospike-client-sdk-workshop/data
: Auto-load complete: LoadResult{total=200, success=200, errors=0, successRate=100.00%}

Example response

The auto-loader reports total=200, success=200, errors=0, which means the application called the stubbed data-access methods 200 times without throwing an exception.

Confirm the empty state in the application UI and in Voyager

The new-client profile selects KeyValueServiceNewClient. The data-access methods in this class are stubbed out and return placeholder values, such as Optional.empty(). The auto-loader does not throw, so the log reports success=200, but no records reach the cluster. You implement these methods in the next section.

Open the application in your browser at http://localhost:8080.

The category dropdowns at the top render, but the home page itself shows an Oops... looks like that page doesn't exist error in place of the product grid.
In the Spring Boot terminal, look at the recent log entries.

Each request to the home page or the cart triggers a java.util.NoSuchElementException: No value present from inside KeyValueServiceNewClient.query and KeyValueServiceNewClient.getCart. This is expected: the stub implementations return Optional.empty() and the controllers call .get() on the result.
Switch to Voyager and select Refresh in the cluster details panel.

The test namespace card still reports 0 SETS, which confirms that the stub methods never wrote a record to the cluster.

Outcomes

You now have:

A single-node Aerospike Database running in Docker on localhost:3000.
Voyager connected to that database, with the test namespace visible.
The Spring Boot retail application running on localhost:8080 with the new-client profile selected.

You cannot yet:

See products on the home page.
Filter products by category, article type, usage, or brand.
Add items to a shopping cart.

In the next section you implement the data-access methods that fill these gaps. Leave Voyager and the Spring Boot application running. You stop and rerun the Spring Boot app each time you change Java code. You can leave Voyager open and select Refresh after each change.