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 docker without sudo)

  • Git

  • Python 3 (python3) with pyyaml available (used by setup.sh helper scripts)

  • An Intel GPU and its Linux driver, available at /dev/dri. The Content Search reranker requires GPU access; setup.sh stops with an error if the GPU device or host render group 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:

  1. Set diarization: true under models.asr in config.yaml.

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

REGISTRY

audio-analyzer, model-downloader, metrics-collector

Compose files

true

Pulled from Docker Hub (intel/audio-analyzer, intel/model-download, intel/retail-benchmark)

docker-compose.yml

false

Built locally from the edge-ai-libraries and performance-tools submodules

docker-compose.yml + docker-compose.local-build.yml

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:

  1. Initializes the edge-ai-libraries (sparse checkout) and performance-tools git submodules.

  2. Installs and verifies the Node.js toolchain for the UI.

  3. Creates .env from .env.example if it does not exist.

  4. Warns if diarization is enabled without HF_TOKEN.

  5. Syncs startup-models.yaml and startup-models.gpu.yaml with config.yaml.

  6. Derives COMPOSE_PROFILES from the enabled features, and sets STARTUP_MODELS_CONFIG only when text-gen is active (so an ASR-only stack’s shared model-downloader skips the OVMS exports).

  7. Requires an Intel GPU (/dev/dri), sets RENDER_GID from the host’s render group, and enables the GPU Compose configuration.

  8. Validates the compose config, then follows REGISTRY in config.yaml: pulls the Docker Hub images when true, or builds them locally when false. The app and video-analytics images are always built locally. Then starts the stack.

  9. Waits for the smart-classroom-app container 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.

  10. Runs npm install and 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#

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, and NO_PROXY for the shell and for Docker.

  • Model Downloads: Stable access to huggingface.co is 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 setup.sh, plus ui/node_modules, ui/vite-dev.log, and ui/vite-dev.pid.

Containers and network

Every service of the smart-classroom Compose project, in all profiles.

Docker volumes

model-cache (downloaded and exported models, the largest item), video-analytics-models, the audio-analyzer-* volumes, and metrics.

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

-y, --yes

Skip the confirmation prompt. Required in a non-interactive shell.

--remove-storage

Also delete storage/ (or the path in STORAGE_DIR), which holds session data and Content Search data (SQLite, ChromaDB, uploads). The container user owns these files, so the script retries with sudo if needed.

--prune-build-cache

Also run docker builder prune -af to free the build layers cached by the app and video-analytics builds. This clears the build cache of every Docker project on the host.

--remove-node

Also remove Node.js (the NodeSource apt or dnf package, and ~/.nvm). setup.sh does not record whether it installed Node.js, so this also removes a Node.js that you installed yourself. After removing ~/.nvm, delete the nvm lines from your shell profile, for example ~/.bashrc.

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.