# 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](./system-requirements.md) 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](https://docs.openedgeplatform.intel.com/dev/OEP-articles/contribution-guide.html#repository-cloning-partial-cloning).
```bash
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.
```yaml
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`.
```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](https://huggingface.co/pyannote/speaker-diarization-community-1) model, create a Read token at [Hugging Face Access Tokens](https://huggingface.co/settings/tokens), then:
1. Set `diarization: true` under `models.asr` in `config.yaml`.
2. Add the token to `.env`:
```bash
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:
```yaml
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](#manual-docker-startup-optional).
## Step 4: Run the Setup Script
From the `Linux` directory, run:
```bash
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:
```text
[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:
- UI: (change with `UI_PORT= ./setup.sh`). If the port is already in use, `setup.sh` uses 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](../linux-docker-architecture.md).
Check status and logs:
```bash
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:
```bash
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](#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:
```bash
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:
```bash
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:
```bash
./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:
```bash
./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`):
```bash
cd ../../..
rm -rf education-ai-suite
```
To check that nothing is left behind:
```bash
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.