Get Started on Linux#
This guide walks you through cloning the repository, configuring defaults, and running the application on Linux using the setup.sh script.
Step 1: Prerequisites#
Make sure the following are installed. See System Requirements for details.
Docker Engine and the Docker Compose plugin (your user must be able to run
dockerwithoutsudo)Git
Python 3 (
python3) withpyyamlavailable (used bysetup.shhelper scripts)An Intel GPU and its Linux driver, available at
/dev/dri. The Content Search reranker requires GPU access;setup.shstops with an error if the GPU device or hostrendergroup is missing.
Note
Node.js for the UI build is provisioned by setup.sh through scripts/node-setup.sh.
Step 2: Clone Repository#
Go to the target directory of your choice and clone the suite.
If you want to clone a specific release branch, replace main with the desired tag.
To learn more about partial cloning, see the Repository Cloning guide.
git clone --filter=blob:none --branch main https://github.com/open-edge-platform/education-ai-suite.git
cd education-ai-suite/smart-classroom/Linux
Step 3: Configuration#
A. Enable Feature Configuration#
Features are enabled or disabled through the features: block in config.yaml. Only enabled features are initialized at startup. setup.sh derives COMPOSE_PROFILES in .env from this block.
features:
asr: { enabled: true } # Speech-to-text transcription
summary: { enabled: true } # AI class summary
mindmap: { enabled: true } # Mind map generation
topic_segmentation: { enabled: true }
video_analytics: { enabled: true } # Video analytics
content_search: { enabled: true } # Multimodal search + RAG service (port 9011)
qa: { enabled: true } # RAG-based Q&A over uploaded materials
B. Default Configuration#
Models are set in config.yaml. Changing models.text_gen.vlm_name, the embedding model, or the content search reranker is picked up by setup.sh, which syncs components/vlm/config/startup-models.yaml and startup-models.gpu.yaml.
asr:
provider: openai # Supported: openvino, openai, funasr
name: whisper-small
device: CPU
text_gen:
provider: vlm
vlm_name: Qwen/Qwen3-VL-8B-Instruct
device: GPU # Options: GPU or CPU
weight_format: int4 # Supported: fp16, int4, int8
max_new_tokens: 5120
C. Hugging Face Token (Optional)#
Speaker diarization (pyannote) and gated models need a Hugging Face token. Request access to the Pyannote Speaker Diarization Community v1 model, create a Read token at Hugging Face Access Tokens, then:
Set
diarization: trueundermodels.asrinconfig.yaml.Add the token to
.env:
HF_TOKEN=hf_your_access_token_here
Note
setup.sh creates .env from .env.example on first run. If you want to set HF_TOKEN beforehand, run cp .env.example .env first. setup.sh warns when diarization is enabled and HF_TOKEN is missing.
D. Docker Image Source (Optional)#
The REGISTRY flag in config.yaml selects where setup.sh gets the third-party images:
REGISTRY: true # true: pull from Docker Hub (default); false: build locally
|
|
Compose files |
|---|---|---|
|
Pulled from Docker Hub ( |
|
|
Built locally from the |
|
The Smart Classroom app and video-analytics images are always built locally. For manual Compose commands, see Manual Docker Startup.
Step 4: Run the Setup Script#
From the Linux directory, run:
chmod +x setup.sh
./setup.sh
The script performs the following:
Initializes the
edge-ai-libraries(sparse checkout) andperformance-toolsgit submodules.Installs and verifies the Node.js toolchain for the UI.
Creates
.envfrom.env.exampleif it does not exist.Warns if diarization is enabled without
HF_TOKEN.Syncs
startup-models.yamlandstartup-models.gpu.yamlwithconfig.yaml.Derives
COMPOSE_PROFILESfrom the enabled features, and setsSTARTUP_MODELS_CONFIGonly whentext-genis active (so an ASR-only stack’s sharedmodel-downloaderskips the OVMS exports).Requires an Intel GPU (
/dev/dri), setsRENDER_GIDfrom the host’srendergroup, and enables the GPU Compose configuration.Validates the compose config, then follows
REGISTRYinconfig.yaml: pulls the Docker Hub images whentrue, or builds them locally whenfalse. The app and video-analytics images are always built locally. Then starts the stack.Waits for the
smart-classroom-appcontainer to become healthy and, when search features are enabled, for Content Search aggregate readiness. Setup exits with an error rather than reporting success if either readiness check times out.Runs
npm installand starts the UI dev server in the background.
Note
First-time execution can take a long time (up to about 30 minutes) while models are downloaded and exported. Override the wait time with HEALTH_TIMEOUT_S, for example HEALTH_TIMEOUT_S=3600 ./setup.sh.
On success you should see:
[setup] ✅ App is healthy: http://localhost:8000/
[setup] ✅ UI: http://localhost:5173/ (logs: .../ui/vite-dev.log)
[setup] ✅ setup complete.
Step 5: Verify and Manage the Application#
Backend: http://localhost:8000/
UI: http://localhost:5173/ (change with
UI_PORT=<port> ./setup.sh). If the port is already in use,setup.shuses the next free one and prints the actual URL.
To see which containers setup.sh starts, how they depend on each other, and which ports they use, see
Linux Docker Architecture.
Check status and logs:
docker compose -f docker/docker-compose.yml ps
docker compose -f docker/docker-compose.yml logs -f app
docker compose -f docker/docker-compose.yml logs -f model-downloader ovms
Stop the services:
docker compose --env-file .env -f docker/docker-compose.yml -f docker/docker-compose.gpu.yml down
kill $(cat ui/vite-dev.pid) # stop the UI dev server
This keeps the Docker volumes (downloaded models) and images so that the next ./setup.sh starts quickly. To remove the application and free the disk space, see Uninstall the Application.
Important
After changing config.yaml, rerun ./setup.sh so that profiles and model lists are regenerated and the stack restarts with the new configuration.
Manual Docker Startup (Optional)#
Use this instead of ./setup.sh to run the Compose commands yourself. Complete
Steps 1–3 first. The reranker requires an Intel GPU at /dev/dri and a host
render group. From smart-classroom/Linux, configure GPU permissions and start
the stack:
test -d /dev/dri || { echo "Required GPU device /dev/dri not found"; exit 1; }
export RENDER_GID="$(getent group render | cut -d: -f3)"
test -n "$RENDER_GID" || { echo "Required render group not found"; exit 1; }
cp -n .env.example .env
python3 -m utils.compose_profiles --write-env
python3 -m utils.sync_startup_models --write
docker compose --env-file .env \
-f docker/docker-compose.yml \
-f docker/docker-compose.gpu.yml \
up -d --build
The default REGISTRY: true in config.yaml pulls intel/audio-analyzer,
intel/model-download and intel/retail-benchmark from Docker Hub. When
REGISTRY: false, add -f docker/docker-compose.local-build.yml to the Compose
command, after the base file and before up. This override builds
smart-classroom-audio-analyzer:local, sc-model-downloader:local and
sc-metrics-collector:local from the edge-ai-libraries and performance-tools
submodules instead of pulling them. To pull the registry images explicitly first,
run the same command with pull --ignore-buildable instead of up -d --build.
RENDER_GID gives the container GPU access. Export it in each new terminal or
save its numeric value in .env. The image includes the Intel GPU runtime;
first startup may take longer while models download.
Verify Content Search readiness:
curl --noproxy '*' http://127.0.0.1:8000/api/v1/system/health
HTTP 200 with "status":"ok" means ready. Use the same Compose command with
logs -f app or down instead of up -d --build to inspect logs or stop services.
Network Requirements#
Proxy: If behind a proxy, configure
HTTP_PROXY,HTTPS_PROXY, andNO_PROXYfor the shell and for Docker.Model Downloads: Stable access to
huggingface.cois required to download pre-trained models.
Uninstall the Application#
The uninstall.sh script reverses setup.sh. From the Linux directory, run:
./uninstall.sh
The script lists what it will remove and asks for confirmation before it changes anything. It removes:
Item |
What is removed |
|---|---|
UI dev server |
The process started by |
Containers and network |
Every service of the |
Docker volumes |
|
Docker images |
The images that the stack pulled or built, including the locally built app and video-analytics images. |
By default the script keeps storage/ (session data and Content Search data), .env, and the source tree.
Options#
Option |
Effect |
|---|---|
|
Skip the confirmation prompt. Required in a non-interactive shell. |
|
Also delete |
|
Also run |
|
Also remove Node.js (the NodeSource |
For example, to remove everything that setup.sh created, without prompts:
./uninstall.sh --yes --remove-storage --prune-build-cache
The script exits with a non-zero status and prints a warning if a step fails, for example when the Docker daemon is not reachable.
Finish the Cleanup#
To also delete the source tree, including the git submodules and .env (which can contain HF_TOKEN):
cd ../../..
rm -rf education-ai-suite
To check that nothing is left behind:
docker volume ls --filter label=com.docker.compose.project=smart-classroom
docker system df
Note
After an uninstall, the next ./setup.sh downloads and exports the models again. This first run can take up to about 30 minutes.