Skip to content

Commit 37223d9

Browse files
streamer45streamer45
authored
feat(docker): add batteries-included demo image (CPU) (#16)
* feat(docker): add batteries-included demo image (CPU) * feat(ci): manual workflow triggers
1 parent 25b9dfc commit 37223d9

File tree

9 files changed

+961
-13
lines changed

9 files changed

+961
-13
lines changed

‎.github/workflows/docker.yml‎

Lines changed: 109 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,32 @@ on:
88
push:
99
tags:
1010
- 'v*.*.*'
11+
workflow_dispatch:
12+
inputs:
13+
tag:
14+
description: "Image tag to publish (defaults to sha-<short>)"
15+
required: false
16+
default: ""
17+
push:
18+
description: "Push to GHCR (disable for build-only smoke test)"
19+
required: false
20+
default: true
21+
type: boolean
22+
build_cpu:
23+
description: "Build CPU image"
24+
required: false
25+
default: true
26+
type: boolean
27+
build_gpu:
28+
description: "Build GPU image"
29+
required: false
30+
default: true
31+
type: boolean
32+
build_demo:
33+
description: "Build demo image"
34+
required: false
35+
default: true
36+
type: boolean
1137

1238
env:
1339
REGISTRY: ghcr.io
@@ -16,6 +42,7 @@ env:
1642
jobs:
1743
build-cpu:
1844
name: Build CPU Image
45+
if: ${{ github.event_name == 'push' || inputs.build_cpu }}
1946
runs-on: self-hosted
2047
permissions:
2148
contents: read
@@ -37,13 +64,22 @@ jobs:
3764
- name: Extract version from tag
3865
id: meta
3966
run: |
40-
VERSION=${GITHUB_REF#refs/tags/}
67+
if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
68+
VERSION=${GITHUB_REF#refs/tags/}
69+
else
70+
VERSION_INPUT='${{ inputs.tag }}'
71+
if [[ -n "${VERSION_INPUT}" ]]; then
72+
VERSION="${VERSION_INPUT}"
73+
else
74+
VERSION="sha-${GITHUB_SHA::12}"
75+
fi
76+
fi
4177
echo "version=${VERSION}" >> $GITHUB_OUTPUT
4278
echo "Building version: ${VERSION}"
4379
{
4480
echo "tags<<EOF"
4581
echo "${REGISTRY}/${IMAGE_NAME}:${VERSION}"
46-
if [[ "$VERSION" != *-* ]]; then
82+
if [[ "${GITHUB_REF}" == refs/tags/* ]] && [[ "$VERSION" != *-* ]]; then
4783
echo "${REGISTRY}/${IMAGE_NAME}:latest"
4884
fi
4985
echo "EOF"
@@ -54,7 +90,7 @@ jobs:
5490
with:
5591
context: .
5692
file: ./Dockerfile
57-
push: true
93+
push: ${{ github.event_name == 'push' || inputs.push }}
5894
tags: ${{ steps.meta.outputs.tags }}
5995
cache-from: type=local,src=/mnt/docker-cache
6096
cache-to: type=local,dest=/mnt/docker-cache,mode=max
@@ -63,6 +99,7 @@ jobs:
6399

64100
build-gpu:
65101
name: Build GPU Image
102+
if: ${{ github.event_name == 'push' || inputs.build_gpu }}
66103
runs-on: self-hosted
67104
permissions:
68105
contents: read
@@ -84,13 +121,22 @@ jobs:
84121
- name: Extract version from tag
85122
id: meta
86123
run: |
87-
VERSION=${GITHUB_REF#refs/tags/}
124+
if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
125+
VERSION=${GITHUB_REF#refs/tags/}
126+
else
127+
VERSION_INPUT='${{ inputs.tag }}'
128+
if [[ -n "${VERSION_INPUT}" ]]; then
129+
VERSION="${VERSION_INPUT}"
130+
else
131+
VERSION="sha-${GITHUB_SHA::12}"
132+
fi
133+
fi
88134
echo "version=${VERSION}" >> $GITHUB_OUTPUT
89135
echo "Building version: ${VERSION}"
90136
{
91137
echo "tags<<EOF"
92138
echo "${REGISTRY}/${IMAGE_NAME}:${VERSION}-gpu"
93-
if [[ "$VERSION" != *-* ]]; then
139+
if [[ "${GITHUB_REF}" == refs/tags/* ]] && [[ "$VERSION" != *-* ]]; then
94140
echo "${REGISTRY}/${IMAGE_NAME}:latest-gpu"
95141
fi
96142
echo "EOF"
@@ -101,7 +147,64 @@ jobs:
101147
with:
102148
context: .
103149
file: ./Dockerfile.gpu
104-
push: true
150+
push: ${{ github.event_name == 'push' || inputs.push }}
151+
tags: ${{ steps.meta.outputs.tags }}
152+
cache-from: type=local,src=/mnt/docker-cache
153+
cache-to: type=local,dest=/mnt/docker-cache,mode=max
154+
platforms: linux/amd64
155+
provenance: false
156+
157+
build-demo:
158+
name: Build Demo Image
159+
if: ${{ github.event_name == 'push' || inputs.build_demo }}
160+
runs-on: self-hosted
161+
permissions:
162+
contents: read
163+
packages: write
164+
steps:
165+
- name: Checkout code
166+
uses: actions/checkout@v5
167+
168+
- name: Set up Docker Buildx
169+
uses: docker/setup-buildx-action@v3
170+
171+
- name: Log in to GitHub Container Registry
172+
uses: docker/login-action@v3
173+
with:
174+
registry: ${{ env.REGISTRY }}
175+
username: ${{ github.actor }}
176+
password: ${{ secrets.GITHUB_TOKEN }}
177+
178+
- name: Extract version from tag
179+
id: meta
180+
run: |
181+
if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
182+
VERSION=${GITHUB_REF#refs/tags/}
183+
else
184+
VERSION_INPUT='${{ inputs.tag }}'
185+
if [[ -n "${VERSION_INPUT}" ]]; then
186+
VERSION="${VERSION_INPUT}"
187+
else
188+
VERSION="sha-${GITHUB_SHA::12}"
189+
fi
190+
fi
191+
echo "version=${VERSION}" >> $GITHUB_OUTPUT
192+
echo "Building version: ${VERSION}"
193+
{
194+
echo "tags<<EOF"
195+
echo "${REGISTRY}/${IMAGE_NAME}:${VERSION}-demo"
196+
if [[ "${GITHUB_REF}" == refs/tags/* ]] && [[ "$VERSION" != *-* ]]; then
197+
echo "${REGISTRY}/${IMAGE_NAME}:latest-demo"
198+
fi
199+
echo "EOF"
200+
} >> "$GITHUB_OUTPUT"
201+
202+
- name: Build and push Demo image
203+
uses: docker/build-push-action@v5
204+
with:
205+
context: .
206+
file: ./Dockerfile.demo
207+
push: ${{ github.event_name == 'push' || inputs.push }}
105208
tags: ${{ steps.meta.outputs.tags }}
106209
cache-from: type=local,src=/mnt/docker-cache
107210
cache-to: type=local,dest=/mnt/docker-cache,mode=max

‎DOCKER.md‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,65 @@ SPDX-License-Identifier: MPL-2.0
1010
> The documentation site is the canonical source for deployment guidance: <https://streamkit.dev/deployment/docker/>.
1111
> This file is a repo-local snapshot for convenience and may lag behind the website docs.
1212
13-
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.
13+
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.
1414

1515
> [!NOTE]
1616
> 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.
1717
18+
## Image Variants
19+
20+
- `Dockerfile` (CPU, slim): includes server + sample pipelines + a few small audio samples; mount models/plugins externally.
21+
- `Dockerfile.gpu` (GPU, slim): includes server + sample pipelines; mount models/plugins externally.
22+
- `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.
23+
24+
### Demo Image Quick Start
25+
26+
```bash
27+
docker build -f Dockerfile.demo -t streamkit:demo .
28+
29+
docker run \
30+
-p 127.0.0.1:4545:4545/tcp \
31+
-p 127.0.0.1:4545:4545/udp \
32+
streamkit:demo
33+
```
34+
35+
If you want the OpenAI-powered sample pipelines, pass `OPENAI_API_KEY` without putting it directly in the command:
36+
37+
```bash
38+
# Option A: inherit from your current shell environment
39+
export OPENAI_API_KEY=sk-...
40+
docker run --env OPENAI_API_KEY \
41+
-p 127.0.0.1:4545:4545/tcp -p 127.0.0.1:4545:4545/udp \
42+
streamkit:demo
43+
44+
# Option B: env-file (recommended for local dev; keep it out of git)
45+
printf 'OPENAI_API_KEY=%s\n' 'sk-...' > streamkit.env
46+
chmod 600 streamkit.env
47+
docker run --env-file streamkit.env \
48+
-p 127.0.0.1:4545:4545/tcp -p 127.0.0.1:4545:4545/udp \
49+
streamkit:demo
50+
```
51+
52+
### Debugging native crashes (gdb)
53+
54+
The demo image includes `gdb`. To attach to the running server inside Docker, run with ptrace enabled:
55+
56+
```bash
57+
docker run --rm --name streamkit-demo \
58+
--cap-add=SYS_PTRACE \
59+
--security-opt seccomp=unconfined \
60+
--user root \
61+
-p 127.0.0.1:4545:4545/tcp -p 127.0.0.1:4545:4545/udp \
62+
streamkit:demo
63+
```
64+
65+
Then, inside the container, the StreamKit server is typically PID 1:
66+
67+
```bash
68+
ps -eo pid,cmd
69+
gdb -p 1
70+
```
71+
1872
## Quick Start
1973

2074
### 1. Build the Image

0 commit comments

Comments
 (0)