Chatqna Docker Deploy

<!--
SPDX-FileCopyrightText: (C) 2026 Intel Corporation
SPDX-License-Identifier: Apache-2.0
-->

ChatQnA Docker Deploy

Deploy the Chat Question and Answer Core sample application as containers using Docker Compose.

Environment setup (run first)

This skill operates on real ChatQnA source files, so the ChatQnA application must be present and commands must run from the app root. Do this before any deploy workflow, whether or not source is already in your workspace.

Run the bundled bootstrap. It searches for an existing ChatQnA checkout by walking up from the current directory and checking the enclosing git repo, then reuses it without re-cloning. Only when no checkout is found does it do a shallow, single-branch, sparse checkout of just sample-applications/chat-question-and-answer-core from main.

It prints the resolved app root on stdout:

# SKILL_DIR is this skill directory. In-repo it is:
# .github/skills/chatqna-docker-deploy
SKILL_DIR=".github/skills/chatqna-docker-deploy"
APP_ROOT="$(bash "$SKILL_DIR/scripts/chatqna-bootstrap.sh")"
cd "$APP_ROOT"

Every command below assumes the working directory is this APP_ROOT.

To use a fork/branch or a specific clone path, override these before running the bootstrap script:

• CHATQNA_REPO_URL
• CHATQNA_REPO_BRANCH
• CHATQNA_CLONE_DIR
• CHATQNA_FORCE_CLONE (set to 1 to force clone)

Codebase root: sample-applications/chat-question-and-answer-core/

What This Skill Produces

• A running ChatQnA Core deployment on one backend profile:
  • OpenVINO CPU (OPENVINO)
  • OpenVINO GPU (OPENVINO-GPU)
  • Ollama CPU (OLLAMA)
• A verified startup state using container status, logs, and health endpoint.
• A concise deployment report containing:
  • runtime profile selected
  • image source used (prebuilt tags or locally built)
  • whether pinned default tags or user-provided tags were used
  • access URL and API docs URL
  • any warnings (token/model/device constraints)

When to Use

• "Deploy chat question and answer core"
• "Start chatqna containers"
• "Run docker compose for chatqna"
• "Deploy OpenVINO GPU profile"
• "Deploy ollama backend"

Inputs To Confirm

Before running commands, confirm or infer these values:

1. Backend/runtime: openvino or ollama
2. Device: cpu or gpu (GPU valid only for OpenVINO)
3. Image source:
   • prebuilt registry images (REGISTRY, BACKEND_TAG, UI_TAG), or
   • local source builds (tags usually latest)
4. Optional model config path: MODEL_CONFIG_PATH
5. Optional Hugging Face token for private/gated models: HUGGINGFACEHUB_API_TOKEN

If runtime/device values are missing, default to openvino + cpu, proceed directly with OpenVINO CPU using source scripts/setup_env.sh.

If prebuilt images are used and tags are not specified by the user, default to pinned release tags.

Use Docker Compose commands only for deployment actions in this skill. Always use the repository compose file path docker/compose.yaml. Do not substitute docker-compose.yml and do not use placeholders such as <compose-file>.

Defaulting Rule (Mandatory)

For prompts like "Deploy chatqna core with docker compose" where runtime or device is omitted:

1. Assume backend=openvino and device=cpu.
2. Run the standard preflight checks.
3. Select profile with source scripts/setup_env.sh.
4. Start with docker compose -f docker/compose.yaml up -d.
5. Verify with docker compose -f docker/compose.yaml ps, docker compose -f docker/compose.yaml logs --tail=150, and health check on /v1/chatqna/health.

Decision Logic

• If backend is ollama:
  • force CPU path
  • use source scripts/setup_env.sh -b ollama
• If backend is openvino and device is gpu:
  • use source scripts/setup_env.sh -d gpu
  • if /dev/dri/render* does not exist, warn and fall back to CPU path
• Else:
  • use source scripts/setup_env.sh (OpenVINO CPU)

Deployment Workflow

Run from sample-applications/chat-question-and-answer-core.

1. Preflight

docker --version
docker compose version

If prebuilt images are requested and the user did not provide tags, use the following as defaults:

export REGISTRY="intel/"
export BACKEND_TAG="core_2026.2.0-rc2"      # or core_gpu_2026.2.0-rc2 / core_ollama_2026.2.0-rc2
export UI_TAG="core_2026.2.0-rc2"

These variable names must match docker/compose.yaml exactly:

• REGISTRY
• BACKEND_TAG
• UI_TAG

Do not use other variable names other than REGISTRY, BACKEND_TAG, and UI_TAG for this workflow. Do not use a generic TAG variable for this workflow. Do not default to latest when tags are omitted.

If the user explicitly provides different tags or registry, use those values instead of the pinned defaults.

Optional model config override:

export MODEL_CONFIG_PATH="/absolute/path/to/config.yaml"

Optional gated/private model token:

export HUGGINGFACEHUB_API_TOKEN="<token>"

For gated/private models, use the variable name exactly as above. Do not replace it with HF_TOKEN in this skill.

2. Select Profile and Export Environment

Choose exactly one:

# OpenVINO CPU (default)
source scripts/setup_env.sh

# OpenVINO GPU
source scripts/setup_env.sh -d gpu

# Ollama CPU
source scripts/setup_env.sh -b ollama

3. Start Containers

Default startup mode is detached:

docker compose -f docker/compose.yaml up -d

4. Verify Deployment

docker compose -f docker/compose.yaml ps
docker compose -f docker/compose.yaml logs --tail=150
curl -sf "http://${HOST_IP:-127.0.0.1}:8102/v1/chatqna/health"
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${HOST_IP:-127.0.0.1}:8102/v1/chatqna/health"

When handling a deploy request, include raw command output in the response as evidence:

• docker compose -f docker/compose.yaml ps output showing expected services as Up.
• Health check output and HTTP status from: curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${HOST_IP:-127.0.0.1}:8102/v1/chatqna/health"

Expected readiness indicators:

• backend container is running
• UI container is running
• nginx container for selected profile is running
• health endpoint returns success

Access ChatQnA application:

• To access the ChatQnA UI: http://<HOST_IP>:8102 or http://localhost:8102
• To access the ChatQnA API docs: http://<HOST_IP>:8102/v1/chatqna/docs or http://localhost:8102/v1/chatqna/docs