# Build From Source
Build Smart Kiosk Assistant from source. Use this path when you need a
code change in any of the kiosk services. To run the prebuilt images
from Docker Hub without rebuilding, see
[Run With Docker Compose](./run-container.md).
## Prerequisites
Verify the [System Requirements](./system-requirements.md).
Beyond Docker, the build and benchmark flows need these host packages:
```bash
sudo apt-get update
sudo apt-get install -y git git-lfs python3-venv ffmpeg
```
- `python3-venv` — `make benchmark` creates a virtualenv for the
performance-tools orchestrator. On Debian/Ubuntu the `venv` module is
packaged separately from `python3`, and without it the benchmark fails
with `ensurepip is not available`.
- `ffmpeg` — used to transcode and resample benchmark/replay audio to the
16 kHz mono PCM the analyzer expects.
## Pinned Upstream Sources
This release depends on **specific commits** of two other repositories.
| Repository | Pinned commit | Why |
| --- | --- | --- |
| [`intel-retail/performance-tools`](https://github.com/intel-retail/performance-tools) | `2595194` | Provides `benchmark_smart_kiosk_v2v.py`, the voice-to-voice benchmark orchestrator, and the natural-endpointing measurement mode. Tracked as a Git **submodule**, so the commit is recorded in this repository — you do not pick it manually. |
| [`open-edge-platform/edge-ai-libraries`](https://github.com/open-edge-platform/edge-ai-libraries) | `audio-analyzer`: `dc12ac9` (`release-2026.3.0` branch)
`text-to-speech`: `62468e8` | Source for the `audio-analyzer` and `text-to-speech` images. You do **not** build these two services here — they are always pulled pre-built from the registry (Docker Hub `intel/audio-analyzer` and `intel/text-to-speech` by default). Both commits include everything this release relies on: `TEXT_TO_SPEECH_WORKERS`, the Kokoro TTS engine, the ASR preview pool, forwarding an empty ASR language to English-only checkpoints, and the realtime low-latency mode. The `audio-analyzer` commit also includes the speechbrain 1.1.2 fix ([open-edge-platform/edge-ai-libraries#3959](https://github.com/open-edge-platform/edge-ai-libraries/pull/3959)), without which the service fails to start when speaker diarization is enabled. |
`audio-analyzer` and `text-to-speech` have **no `build:` section** in
`docker-compose.yml` — neither `docker compose build` nor
`make build REGISTRY=false` ever rebuilds them from source. To change
either service, build and push its image from an `edge-ai-libraries`
checkout at its pinned commit (see
[Rebuilding the External TTS/ASR Images](#rebuilding-the-external-ttsasr-images)),
then pull it here.
## Clone and Prepare
Only this repository needs to be on disk to build the kiosk services.
`audio-analyzer` and `text-to-speech` are pulled as pre-built images (see
[Pinned Upstream Sources](#pinned-upstream-sources)), so no
`edge-ai-libraries` checkout is required for a normal build-from-source
run.
From whatever parent directory you keep the source in, run:
```bash
# --recurse-submodules checks out performance-tools at the commit this
# repository pins. Without it the submodule directory is empty and
# `make benchmark` cannot find the benchmark orchestrator.
git clone --recurse-submodules -b main --single-branch \
https://github.com/intel-retail/voice-enabled-interactions.git
cd voice-enabled-interactions/smart-kiosk-assistant/
# Already cloned without --recurse-submodules? Run this instead:
# make update-submodules
```
Confirm the submodule pin before building:
```bash
git -C ../performance-tools rev-parse --short HEAD # expect 2595194
```
You only need an `edge-ai-libraries` checkout if you intend to rebuild
the external ASR/TTS images yourself — see
[Rebuilding the External TTS/ASR Images](#rebuilding-the-external-ttsasr-images).
## Create the Environment File
`.env` is not committed to the repo. `docker-compose.yml` reads
`REGISTRY_REPO`/`RELEASE_TAG` from it and falls back to `2026.3.0-rc2` if
it's missing, so create it before building:
```bash
make init-env # copies .env.example → .env
```
`.env.example` ships `REGISTRY=true`, which makes `make build` **pull the
released images instead of building your source**. That is the right
default for the pull flow, but it is not what you want here. For a
build-from-source run, either pass the override each time:
```bash
make build REGISTRY=false
```
or edit `.env` once and set `REGISTRY=false`. `docker compose build`
(used later on this page) is unaffected — it always builds.
## Download the LLM Model for OVMS
Before building or starting the stack, download the Qwen3-4B model that
OVMS serves. This runs once and caches into `./models/`:
```bash
# GPU (recommended)
./setup_models.sh
# CPU only
./setup_models.sh --device CPU
# Smaller INT4 model
./setup_models.sh --int4
```
`setup_models.sh` downloads the pre-converted OpenVINO™ model from
HuggingFace Hub and updates `OVMS_MODEL_NAME`, `TARGET_DEVICE`, and
`RENDER_GID` in `.env`. See `./setup_models.sh --help` for all options.
## Build All Images With Compose
The top-level [docker-compose.yml](https://github.com/intel-retail/voice-enabled-interactions/blob/main/smart-kiosk-assistant/docker-compose.yml)
declares both `image:` and `build:` for the three services whose source lives in
this repository: `rag-service`, `kiosk-core`, and `kiosk-ui`. `audio-analyzer`
and `text-to-speech` are declared `image:`-only — their source lives in the
sibling `edge-ai-libraries` repo, so `docker compose build` in this repo does
**not** build them (see
[Build the speech-service images](#build-a-single-service-image-directly)
below). Both `REGISTRY_REPO` and `RELEASE_TAG` are read from `.env` (created in
[Create the Environment File](#create-the-environment-file) above;
defaults: `REGISTRY_REPO=intel`, `RELEASE_TAG` pins the current release).
`docker compose build` rebuilds the three in-repo services from source and tags
each result as the same `${REGISTRY_REPO}/:${RELEASE_TAG}` reference used by
the pull flow, so subsequent `docker compose up` calls reuse the local
build until you `docker compose pull` again. Build the two speech-service images
separately (next-but-one section) before the first `up`.
```bash
docker compose build # rag-service, kiosk-core, kiosk-ui
docker compose up -d
```
All services run as UID/GID `1000:1000` (baked into each image),
and runtime data lives in named Docker volumes initialized with that
ownership, so no host UID/GID configuration is needed.
## Rebuild A Single Service
Rebuild only the in-repo service whose source you changed (`rag-service`,
`kiosk-core`, or `kiosk-ui`):
```bash
docker compose build kiosk-core
docker compose up -d kiosk-core
```
`docker compose build audio-analyzer` / `text-to-speech` prints
`No services to build` and exits 0 — those images are built directly from the
`edge-ai-libraries` sources (next section), not from this compose file.
## Build A Single Service Image Directly
Each in-repo service can be built directly with `docker build`. From the
`smart-kiosk-assistant` directory:
```bash
# rag-service
docker build -t intel/rag-service:local ./rag-service
# kiosk-core
docker build -t intel/kiosk-core:local .
# kiosk-ui (React SPA served by nginx)
docker build -t intel/kiosk-ui:local ./kiosk-ui
```
The `kiosk-ui` image serves both the operator screen and the customer
screen; the mode is selected at container start via `KIOSK_UI_MODE`.
## Rebuilding the External TTS/ASR Images
`audio-analyzer` and `text-to-speech` are **not** part of this
repository and are not built by the kiosk flows above. You only need
this if you are changing the ASR or TTS service itself. Check out
`edge-ai-libraries` at the pinned commit, build the image, tag it to
match the `REGISTRY`/`RELEASE_TAG` this stack pulls, and push (or just
build locally and leave it cached):
```bash
git clone --filter=blob:none --sparse \
https://github.com/open-edge-platform/edge-ai-libraries.git
git -C edge-ai-libraries sparse-checkout set \
microservices/audio-analyzer microservices/text-to-speech
git -C edge-ai-libraries fetch origin release-2026.3.0
# audio-analyzer (its Dockerfile lives in docker/)
git -C edge-ai-libraries checkout dc12ac9
docker build -t intel/audio-analyzer:latest \
-f edge-ai-libraries/microservices/audio-analyzer/docker/Dockerfile \
edge-ai-libraries/microservices/audio-analyzer
# text-to-speech
git -C edge-ai-libraries checkout 62468e8
docker build -t intel/text-to-speech:latest \
edge-ai-libraries/microservices/text-to-speech
```
A shallow `--depth 1` clone cannot check out an arbitrary commit, so it
is omitted above. After building, `docker compose up -d` picks up the
freshly tagged local images without a pull.
## Verifying the Build
Once the stack is started, confirm every service is healthy:
```bash
curl --noproxy '*' http://127.0.0.1:8010/health # audio-analyzer
curl --noproxy '*' http://127.0.0.1:8011/health # text-to-speech
curl --noproxy '*' http://127.0.0.1:8020/health # rag-service
curl --noproxy '*' http://127.0.0.1:8012/health # kiosk-core
```
A `{"status": "ok"}` response from each endpoint confirms the build is
functional. Open `http://127.0.0.1:7860` to use the browser UI.