feat(docker): add batteries-included demo image (CPU)

.github/workflows/docker.yml

@@ -8,6 +8,32 @@ on:
   push:
     tags:
       - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Image tag to publish (defaults to sha-<short>)"
+        required: false
+        default: ""
+      push:
+        description: "Push to GHCR (disable for build-only smoke test)"
+        required: false
+        default: true
+        type: boolean
+      build_cpu:
+        description: "Build CPU image"
+        required: false
+        default: true
+        type: boolean
+      build_gpu:
+        description: "Build GPU image"
+        required: false
+        default: true
+        type: boolean
+      build_demo:
+        description: "Build demo image"
+        required: false
+        default: true
+        type: boolean
 
 env:
   REGISTRY: ghcr.io
@@ -16,6 +42,7 @@ env:
 jobs:
   build-cpu:
     name: Build CPU Image
+    if: ${{ github.event_name == 'push' || inputs.build_cpu }}
     runs-on: self-hosted
     permissions:
       contents: read
@@ -37,13 +64,22 @@ jobs:
       - name: Extract version from tag
         id: meta
         run: |
-          VERSION=${GITHUB_REF#refs/tags/}
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION=${GITHUB_REF#refs/tags/}
+          else
+            VERSION_INPUT='${{ inputs.tag }}'
+            if [[ -n "${VERSION_INPUT}" ]]; then
+              VERSION="${VERSION_INPUT}"
+            else
+              VERSION="sha-${GITHUB_SHA::12}"
+            fi
+          fi
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
           echo "Building version: ${VERSION}"
           {
             echo "tags<<EOF"
             echo "${REGISTRY}/${IMAGE_NAME}:${VERSION}"
-            if [[ "$VERSION" != *-* ]]; then
+            if [[ "${GITHUB_REF}" == refs/tags/* ]] && [[ "$VERSION" != *-* ]]; then
               echo "${REGISTRY}/${IMAGE_NAME}:latest"
             fi
             echo "EOF"
@@ -54,7 +90,7 @@ jobs:
         with:
           context: .
           file: ./Dockerfile
-          push: true
+          push: ${{ github.event_name == 'push' || inputs.push }}
           tags: ${{ steps.meta.outputs.tags }}
           cache-from: type=local,src=/mnt/docker-cache
           cache-to: type=local,dest=/mnt/docker-cache,mode=max
@@ -63,6 +99,7 @@ jobs:
 
   build-gpu:
     name: Build GPU Image
+    if: ${{ github.event_name == 'push' || inputs.build_gpu }}
     runs-on: self-hosted
     permissions:
       contents: read
@@ -84,13 +121,22 @@ jobs:
       - name: Extract version from tag
         id: meta
         run: |
-          VERSION=${GITHUB_REF#refs/tags/}
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION=${GITHUB_REF#refs/tags/}
+          else
+            VERSION_INPUT='${{ inputs.tag }}'
+            if [[ -n "${VERSION_INPUT}" ]]; then
+              VERSION="${VERSION_INPUT}"
+            else
+              VERSION="sha-${GITHUB_SHA::12}"
+            fi
+          fi
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
           echo "Building version: ${VERSION}"
           {
             echo "tags<<EOF"
             echo "${REGISTRY}/${IMAGE_NAME}:${VERSION}-gpu"
-            if [[ "$VERSION" != *-* ]]; then
+            if [[ "${GITHUB_REF}" == refs/tags/* ]] && [[ "$VERSION" != *-* ]]; then
               echo "${REGISTRY}/${IMAGE_NAME}:latest-gpu"
             fi
             echo "EOF"
@@ -101,7 +147,64 @@ jobs:
         with:
           context: .
           file: ./Dockerfile.gpu
-          push: true
+          push: ${{ github.event_name == 'push' || inputs.push }}
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=local,src=/mnt/docker-cache
+          cache-to: type=local,dest=/mnt/docker-cache,mode=max
+          platforms: linux/amd64
+          provenance: false
+
+  build-demo:
+    name: Build Demo Image
+    if: ${{ github.event_name == 'push' || inputs.build_demo }}
+    runs-on: self-hosted
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version from tag
+        id: meta
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION=${GITHUB_REF#refs/tags/}
+          else
+            VERSION_INPUT='${{ inputs.tag }}'
+            if [[ -n "${VERSION_INPUT}" ]]; then
+              VERSION="${VERSION_INPUT}"
+            else
+              VERSION="sha-${GITHUB_SHA::12}"
+            fi
+          fi
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "Building version: ${VERSION}"
+          {
+            echo "tags<<EOF"
+            echo "${REGISTRY}/${IMAGE_NAME}:${VERSION}-demo"
+            if [[ "${GITHUB_REF}" == refs/tags/* ]] && [[ "$VERSION" != *-* ]]; then
+              echo "${REGISTRY}/${IMAGE_NAME}:latest-demo"
+            fi
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Build and push Demo image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile.demo
+          push: ${{ github.event_name == 'push' || inputs.push }}
           tags: ${{ steps.meta.outputs.tags }}
           cache-from: type=local,src=/mnt/docker-cache
           cache-to: type=local,dest=/mnt/docker-cache,mode=max

DOCKER.md

@@ -10,11 +10,65 @@ SPDX-License-Identifier: MPL-2.0
 > The documentation site is the canonical source for deployment guidance: <https://streamkit.dev/deployment/docker/>.
 > This file is a repo-local snapshot for convenience and may lag behind the website docs.
 
-This guide covers building and running StreamKit Docker images. The Docker images are slim (~200-400+ MB) and contain the server binary (with the web UI embedded), sample pipelines, and a few small audio samples. Models and plugins must be mounted externally.
+This guide covers building and running StreamKit Docker images. The official “slim” images are small (~200-400+ MB) and contain the server binary (with the web UI embedded), sample pipelines, and a few small audio samples; models and plugins must be mounted externally.
 
 > [!NOTE]
 > Official Docker images are published for `linux/amd64` (x86_64). On ARM hosts (Raspberry Pi, Apple Silicon, etc.), use “Build from Source” or run with amd64 emulation.
 
+## Image Variants
+
+- `Dockerfile` (CPU, slim): includes server + sample pipelines + a few small audio samples; mount models/plugins externally.
+- `Dockerfile.gpu` (GPU, slim): includes server + sample pipelines; mount models/plugins externally.
+- `Dockerfile.demo` (CPU, demo): bundles core native plugins and the models needed by the shipped sample pipelines (including Helsinki OPUS-MT and SenseVoice). This image is much larger and intended for demos/evaluation, not production.
+
+### Demo Image Quick Start
+
+```bash
+docker build -f Dockerfile.demo -t streamkit:demo .
+
+docker run \
+  -p 127.0.0.1:4545:4545/tcp \
+  -p 127.0.0.1:4545:4545/udp \
+  streamkit:demo
+```
+
+If you want the OpenAI-powered sample pipelines, pass `OPENAI_API_KEY` without putting it directly in the command:
+
+```bash
+# Option A: inherit from your current shell environment
+export OPENAI_API_KEY=sk-...
+docker run --env OPENAI_API_KEY \
+  -p 127.0.0.1:4545:4545/tcp -p 127.0.0.1:4545:4545/udp \
+  streamkit:demo
+
+# Option B: env-file (recommended for local dev; keep it out of git)
+printf 'OPENAI_API_KEY=%s\n' 'sk-...' > streamkit.env
+chmod 600 streamkit.env
+docker run --env-file streamkit.env \
+  -p 127.0.0.1:4545:4545/tcp -p 127.0.0.1:4545:4545/udp \
+  streamkit:demo
+```
+
+### Debugging native crashes (gdb)
+
+The demo image includes `gdb`. To attach to the running server inside Docker, run with ptrace enabled:
+
+```bash
+docker run --rm --name streamkit-demo \
+  --cap-add=SYS_PTRACE \
+  --security-opt seccomp=unconfined \
+  --user root \
+  -p 127.0.0.1:4545:4545/tcp -p 127.0.0.1:4545:4545/udp \
+  streamkit:demo
+```
+
+Then, inside the container, the StreamKit server is typically PID 1:
+
+```bash
+ps -eo pid,cmd
+gdb -p 1
+```
+
 ## Quick Start
 
 ### 1. Build the Image