Skip to content

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 FastAPI 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 application logs and Voyager, that the database is reachable but that the application’s data-access methods do not yet write product records.

This step assumes you have completed the tutorial prerequisites: Docker, Python 3.10+, 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.

  1. 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.

  2. Confirm the container is running and reports a healthy status.

    Terminal window
    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 sidebar with Data Browser, MCP Server, and Settings. A Clusters pane lists your clusters under My clusters. A right-hand column shows details for the selected cluster.

  1. Launch Voyager.

    Voyager main window with three columns: left-hand toolbar, middle cluster list, and right-hand cluster details panel

  2. In the cluster list (middle column), select Connect cluster.

  3. 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:

    FieldValue
    NameRetail Demo (or any name you prefer)
    Hostlocalhost
    Port3000
    TLSOff
    Username / PasswordLeave blank
    Voyager connect cluster dialog with name Retail Demo, host localhost, port 3000, and TLS disabled

  4. Select the Connect button.

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

  5. 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. Docker Compose mounts the workshop’s config/aerospike/aerospike.conf, which defines that namespace for the local container.

    Voyager showing the Retail Demo cluster open with the test namespace card 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.

Run the FastAPI application

The FastAPI application uses the new-client profile, which selects the implementation class you edit in later steps (KeyValueServiceNewClient). Set the profile with the AEROSPIKE_CLIENT_PROFILE environment variable. The application listens on port 8080, creates five secondary indexes, and auto-loads 200 sample JSON files from the data/styles/ folder.

  1. Change into the python-server directory and install the application in editable mode.

    Terminal window
    cd python-server
    python -m pip install -e .
    Successfully installed aerospike-client-sdk-workshop-python-1.0.0 aerospike-sdk-...
    Example response

  2. Run the application with the new-client profile.

    Terminal window
    AEROSPIKE_CLIENT_PROFILE=new-client AEROSPIKE_PORT=3000 \
      uvicorn aerospikeworkshop.main:app --host 0.0.0.0 --port 8080

    The application logs include several lines that confirm a successful startup. Uvicorn prints a few lifecycle lines around the application’s own startup messages:

    INFO:     Started server process [70821]
    INFO:     Waiting for application startup.
    INFO:     Started with client profile: new-client
    INFO:     Created secondary index: cat_idx on bin category
    INFO:     Created secondary index: subCat_idx on bin subCategory
    INFO:     Created secondary index: usage_idx on bin usage
    INFO:     Created secondary index: brand_idx on bin brandName
    INFO:     Created secondary index: article_idx on bin articleType
    INFO:     Auto-loading sample data from /.../aerospike-client-sdk-workshop/data
    INFO:     Auto-load complete: processed 200/200 sample files (0 errors); 0 products in products set; category metadata updated in cat_index set
    INFO:     Application startup complete.
    INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
    Example response

    The auto-loader processes every sample JSON file under data/styles/. With the skeleton new-client profile, each file is parsed and category metadata is written to the cat_index set through load_categories, but store_product is still a stub, so no records land in the products set. That is why the log reports 0 products in products set even though it also reports processed 200/200 sample files. A file counts as processed when parsing and category loading succeed without an exception—not when a product record is stored.

Confirm the empty state in the application UI and in Voyager

The new-client profile selects KeyValueServiceNewClient. The data-access methods you implement in the next section are stubbed out: store_product is a no-op and query returns empty lists. Auto-load still writes category metadata to the cat_index set through load_categories, so the category dropdowns may populate, but no product records reach the products set until you implement store_product. You implement these methods in the next section.

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

    The category dropdowns at the top populate because auto-load writes category metadata, but the product rows for Shoes, Bags, Wallets, Watches, and Headwear are empty.

  2. Switch to Voyager and select Refresh in the cluster details panel.

    After refresh, the test namespace shows 2 sets: cat_index with 1 record (category metadata from auto-load) and products with 0 records. That confirms the stub store_product method never wrote product records to the cluster.

    Voyager showing the test namespace with cat_index at 1 record and products at 0 records after the application has run

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 FastAPI 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 FastAPI application running. Stop and restart the server each time you change Python code (or use --reload). You can leave Voyager open and select Refresh after each change.