Merge branch 'feature/KASM-8210_bump_dep_versions_for_1_19_0' into 'develop'

KASM-8210 install_squid: pin to feature-branch builder + adapter artifacts for 1.19.0

Closes KASM-8210

See merge request kasm-technologies/internal/workspaces-core-images!367
This commit is contained in:
Richard Koliser 2026-05-18 16:24:26 +00:00
commit 79473c2338
14 changed files with 227 additions and 32 deletions

View file

@ -1,9 +1,9 @@
############
# Settings #
############
image: docker:29.4.0
image: docker:29.4.3
services:
- docker:29.4.0-dind
- docker:29.4.3-dind
include:
- template: Code-Quality.gitlab-ci.yml

191
CLAUDE.md Normal file
View file

@ -0,0 +1,191 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
**workspaces-core-images** produces the base ("core") Docker images from which every other Kasm Workspaces image is derived. These images bundle a Linux desktop environment, a VNC/browser-access stack (KasmVNC), and the in-container wiring that lets a workspace integrate with the Kasm platform (audio, clipboard, uploads/downloads, webcam, microphone, printing, profile sync, session recording, etc.).
The output is a family of images published as `kasmweb/core-<distro>:<tag>` (e.g. `kasmweb/core-ubuntu-noble`, `kasmweb/core-fedora-41`, `kasmweb/core-alpine-321`). Downstream repos — notably `workspaces-images` (single-app images like Chrome, Firefox, VS Code) and customer-built workspaces — inherit `FROM` these core images.
Related repos in the broader Kasm system:
- `kasm_backend` (parent of this clone) — the backend services that orchestrate workspaces
- `workspaces-images` — application-specific images built on top of these cores
- `KasmVNC` — the VNC server that renders the desktop to a browser
- `kasm_squid_adapter`, `kasm_upload_service`, `kasm_printer_service`, `kasm-webcam-server`, `kasm-gamepad-server`, `profile-sync`, `kasm_smartcard_bridge`, `kasm_websocket_relay`, `kasm_audio_input_server`, `kasm_recorder_service`, `kasm-squid-builder` — component binaries pulled in at image build time
## Repository Layout
```
workspaces-core-images/
├── dockerfile-kasm-core # Debian/Ubuntu family (default)
├── dockerfile-kasm-core-alpine # Alpine
├── dockerfile-kasm-core-centos # CentOS 7
├── dockerfile-kasm-core-fedora # Fedora
├── dockerfile-kasm-core-kasmos # KasmOS (Debian bookworm slim)
├── dockerfile-kasm-core-oracle # Oracle Linux / RHEL / Rocky / Alma
├── dockerfile-kasm-core-suse # openSUSE
├── src/
│ ├── common/ # Shared across all distros
│ │ ├── install/ # kasm_vnc, profile_sync configs
│ │ ├── resources/images/ # Backgrounds, icons, branding
│ │ ├── scripts/kasm_hook_scripts # Session lifecycle hooks (see below)
│ │ └── startup_scripts/ # vnc_startup.sh and friends
│ │
│ ├── ubuntu/ # Ubuntu/Debian install scripts
│ │ ├── install/ # One subdir per feature (audio, webcam, …)
│ │ ├── xfce/ # XFCE desktop configs
│ │ └── icewm/ # IceWM (lightweight alt) configs
│ │
│ ├── alpine/ centos/ fedora*/ kasmos/
│ ├── opensuse/ oracle7/ oracle8/ oracle9/
│ ├── rhel9/ rockylinux*/ almalinux*/
│ ├── parrotos6/ kali/ # Distro-specific install scripts
├── ci-scripts/ # GitLab CI build/test/manifest tooling
│ ├── build.sh, test.sh # Called per matrix row from .gitlab-ci.yml
│ ├── template-gitlab.py # Jinja2 renderer for gitlab-ci.template
│ ├── template-vars.yaml # Matrix of images to build + change-file rules
│ ├── gitlab-ci.template # The actual CI config, rendered dynamically
│ ├── manifest.sh # Multi-arch manifest assembly
│ ├── scan/, vulnerability-filter.rego # Trivy scan + Rego filtering
│ └── readme.sh, quay_readme.sh # Dockerhub/Quay README publishing
├── bin/ # Prebuilt helpers shipped into images
│ ├── intel-gpu-dri3, intel-gpu-virtualgl, intel-gpu-zink
├── docs/core-<distro>/ # Per-image README/description for Dockerhub
│ # (README.md, description.txt, demo.txt)
└── kasm-desktop-kde/ # KDE desktop variant (WIP/placeholder)
```
## What's inside a core image
Every dockerfile follows the same shape — a series of `COPY` + `RUN bash $INST_SCRIPTS/<feature>/install_<feature>.sh` blocks — and installs (roughly in order):
1. **Package rules** — apt/yum/apk pinning and repo setup
2. **Base tools** — curl, jq, sudo, xz, etc.
3. **Fonts** — custom Kasm fonts + distro fonts
4. **Desktop environment** — XFCE (default), IceWM (lightweight), or KDE variant
5. **KasmVNC** — the browser-accessible VNC server (heart of the image)
6. **profile_sync** — persists user profile to object storage between sessions
7. **kasm_upload_server** — handles browser-initiated file uploads/downloads
8. **Audio output** (`kasm_websocket_relay`) — PulseAudio → WebSocket bridge for audio streaming
9. **Audio input** (`kasm_audio_input_server`) — microphone passthrough from browser
10. **Gamepad** (`kasm_gamepad_server`) — HID passthrough from browser
11. **Webcam** (`kasm_webcam_server`) — virtual webcam device
12. **Printer** (`kasm_printer_service`) — CUPS + start_cups.sh
13. **Recorder** (`kasm_recorder_service`) — session recording via FFmpeg + KasmVNC capture
14. **Cursors** — custom cursor theme
15. **Squid** (`kasm_squid_adapter` + `kasm-squid-builder`) — per-session egress proxy
16. **Smartcard** (`kasm_smartcard_bridge`) — CCID/pcscd passthrough
17. **NVIDIA / VirtualGL** — optional GPU acceleration
18. **Hook scripts**`src/common/scripts/kasm_hook_scripts/` (see below)
19. **Cleanup** — strip caches, man pages, locales to shrink layers
Environment variables set by every core image:
- `HOME=/home/kasm-default-profile` — template profile copied to `/home/kasm-user` at startup
- `STARTUPDIR=/dockerstartup` — houses `vnc_startup.sh` and the hook scripts
- `INST_SCRIPTS=/dockerstartup/install` — scratch dir used only during build (removed after each install)
- `KASM_VNC_PATH=/usr/share/kasmvnc`
## Runtime lifecycle
Containers start at `vnc_startup.sh` (in `src/common/startup_scripts/`). It:
1. Logs to the Kasm API via `KASM_API_JWT` / `KASM_API_HOST` / `KASM_API_PORT` if set
2. Regenerates the container user (`generate_container_user`) so UIDs match the workspace config
3. Starts dbus, PulseAudio, KasmVNC, the desktop (XFCE by default, overridable via `START_XFCE4` / `START_ICEWM` / etc.), kasm_upload_server, the squid adapter, cups, profile_sync, the recorder
4. Invokes lifecycle hook scripts in `src/common/scripts/kasm_hook_scripts/` at the right moments:
- `kasm_post_run_root.sh` — runs as root after core services are up
- `kasm_post_run_user.sh` — runs as `kasm-user` after login
- `kasm_pre_shutdown_root.sh` / `kasm_pre_shutdown_user.sh` — graceful teardown
- `kasm_end_session_recoverable.sh` — for persistent/resumable sessions
5. Tails the running processes; exits when the main desktop process dies
Downstream images can override hooks by placing replacements at the same path during their own build.
## Build system
### Local / manual build
The README shows the user-facing form:
```bash
sudo docker run --rm -it --shm-size=512m -p 6901:6901 \
-e VNC_PW=password --build-arg START_XFCE4=1 \
kasmweb/core-ubuntu-noble:<tag>
```
For building from source, each dockerfile takes these build args:
- `BASE_IMAGE` — e.g. `ubuntu:24.04`, `fedora:41`, `alpine:3.21`
- `DISTRO` — selects which `src/<distro>/` tree of install scripts to copy
- `BG_IMG` — which wallpaper from `src/common/resources/images/` to use
- `EXTRA_SH` — optional extra install script (defaults to `noop.sh`)
```bash
docker build \
-f dockerfile-kasm-core \
--build-arg BASE_IMAGE=ubuntu:24.04 \
--build-arg DISTRO=ubuntu \
--build-arg BG_IMG=bg_kasm.png \
-t kasmweb/core-ubuntu-noble:dev .
```
### GitLab CI
The CI pipeline is **dynamically generated**:
1. `template-gitlab.py` reads `template-vars.yaml` (matrix of image names, base images, dockerfiles, change-file globs)
2. It renders `gitlab-ci.template` (Jinja2) into a `.gitlab-ci-child.yml`
3. GitLab runs that child pipeline with stages: build → test → scan → manifest → release
Key scripts invoked from the template:
- `ci-scripts/build.sh NAME1 NAME2 BASE BG DISTRO DOCKERFILE` — per-arch build, pushes to private image cache
- `ci-scripts/test.sh ... ARCH AWS_ID AWS_KEY` — spins up an EC2 instance to smoke-test the image
- `ci-scripts/manifest.sh` / `weekly-manifest.sh` — joins x86_64 + aarch64 into a single multi-arch manifest
- `ci-scripts/scan/` + `vulnerability-filter.rego` — Trivy CVE scan with Rego-based allowlist
- `ci-scripts/readme.sh`, `quay_readme.sh` — push the per-image `docs/core-*/README.md` to Dockerhub/Quay
`FILE_LIMITS` gating: on feature branches the pipeline only builds images whose `files:` globs in `template-vars.yaml` actually changed. `develop` and `release/*` branches build everything. `UNIVERSAL_CHANGE_FILES` (at the top of `template-vars.yaml`) is the set of paths that force rebuilding every image — edit those conservatively.
## Common tasks
**Add support for a new distro version:**
1. Add a block to `template-vars.yaml` (`images:` list) with its name, base image, dockerfile, and change-file globs
2. Create `src/<distro>/install/` trees if a new family (usually just reuse ubuntu/fedora/alpine/etc.)
3. Add `docs/core-<distro>/` with `README.md`, `description.txt`, `demo.txt`
4. Verify change-file globs pick up the right paths on feature-branch builds
**Add a new in-container feature (e.g., new passthrough device):**
1. Create `src/ubuntu/install/<feature>/install_<feature>.sh` (and peers for other distro families)
2. Add `COPY` + `RUN bash $INST_SCRIPTS/<feature>/install_<feature>.sh` to every relevant dockerfile
3. Wire the feature into `src/common/startup_scripts/vnc_startup.sh` if it needs a runtime process
4. Add the path to `UNIVERSAL_CHANGE_FILES` in `template-vars.yaml` so all images rebuild on change
**Debug a failing image at runtime:**
- Start with `-e VNC_PW=password` and connect to `https://<host>:6901` as `kasm_user` / `password`
- Check `/var/log/kasm-*` and the container's stdout (vnc_startup.sh logs go there)
- If running inside a real Kasm deployment, logs are also forwarded to the Kasm API via the `KASM_API_JWT` path in vnc_startup.sh
## Conventions / gotchas
- **Install scripts run at build time only.** `$INST_SCRIPTS` is removed after each install step — do not reference it from runtime code.
- **Downstream images inherit everything.** Be conservative when adding packages; a 50MB addition to a core image fans out across every application image.
- **Multi-arch.** Every dockerfile must work on both `amd64` and `arm64`. Shell out to `$(arch)` or `dpkg --print-architecture` rather than hardcoding.
- **No secrets in images.** Anything in `$HOME/kasm-default-profile` ships in the public image.
- **Cleanup matters.** Each feature's install script is expected to remove its own build-time caches before the layer closes (`apt clean`, `rm -rf /var/lib/apt/lists/*`, etc.) — missing cleanup bloats every downstream image.
- **`dockerfile-kasm-core` is the reference.** The other dockerfiles are variants with equivalent structure; when adding a feature, update them all in the same commit to avoid drift.
## License
See `LICENSE.md` (Kasm Technologies license, not OSS).

View file

@ -9,7 +9,7 @@ DISTRO=$5
DOCKERFILE=$6
## Build/Push image to cache endpoint by pipeline ID ##
docker build \
docker build --provenance=false \
-t ${ORG_NAME}/image-cache-private:$(arch)-core-${NAME1}-${NAME2}-${SANITIZED_BRANCH}-${CI_PIPELINE_ID} \
--build-arg BASE_IMAGE="${BASE}" \
--build-arg DISTRO="${DISTRO}" \

View file

@ -1,9 +1,9 @@
############
# Settings #
############
image: docker:29.4.0
image: docker:29.4.3
services:
- docker:29.4.0-dind
- docker:29.4.3-dind
stages:
- readme
- revert
@ -18,11 +18,9 @@ variables:
TEST_INSTALLER: "{{ TEST_INSTALLER }}"
DOCKER_HOST: tcp://docker:2375
DOCKER_TLS_CERTDIR: ""
DOCKER_AUTH_CONFIG: ${_DOCKER_AUTH_CONFIG}
MIRROR_ORG_NAME: "{{ MIRROR_ORG_NAME }}"
before_script:
- docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
- if [ "$CI_COMMIT_REF_PROTECTED" == "true" ]; then docker login --username $QUAY_USERNAME --password $QUAY_PASSWORD quay.io; fi
- if [ "$CI_COMMIT_REF_PROTECTED" == "true" ]; then docker login --username $GHCR_USERNAME --password $GHCR_PASSWORD ghcr.io; fi
- export SANITIZED_BRANCH="$(echo ${CI_COMMIT_REF_NAME:0:64} | sed -r 's#^release/##' | sed 's/\//_/g')"
include:
@ -44,9 +42,9 @@ include:
{% for IMAGE in multiImages %}
build_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
stage: build
image: docker:28.2.2
image: docker:29.4.3
services:
- docker:28.2.2-dind
- docker:29.4.3-dind
extends:
- .run_rules
- .monitor-in-grafana
@ -77,9 +75,9 @@ build_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
{% for IMAGE in singleImages %}
build_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
stage: build
image: docker:28.2.2
image: docker:29.4.3
services:
- docker:28.2.2-dind
- docker:29.4.3-dind
extends:
- .run_rules
- .monitor-in-grafana
@ -195,6 +193,7 @@ scan_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
{% endfor %}{% endif %}
script:
- apk add bash curl
- mkdir -p ~/.docker && echo "$DOCKER_AUTH_CONFIG" > ~/.docker/config.json
- (cd ci-scripts && bash download-trivy)
- bash ci-scripts/scan image ${ORG_NAME}/image-cache-private:$(arch)-core-{{ IMAGE.name1 }}-{{ IMAGE.name2 }}-${SANITIZED_BRANCH}-${CI_PIPELINE_ID}
needs:
@ -234,6 +233,7 @@ scan_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
{% endfor %}{% endif %}
script:
- apk add bash curl
- mkdir -p ~/.docker && echo "$DOCKER_AUTH_CONFIG" > ~/.docker/config.json
- (cd ci-scripts && bash download-trivy)
- bash ci-scripts/scan image ${ORG_NAME}/image-cache-private:x86_64-core-{{ IMAGE.name1 }}-{{ IMAGE.name2 }}-${SANITIZED_BRANCH}-${CI_PIPELINE_ID}
needs:
@ -253,9 +253,9 @@ scan_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
{% for IMAGE in multiImages %}
manifest_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
stage: manifest
image: docker:28.2.2
image: docker:29.4.3
services:
- docker:28.2.2-dind
- docker:29.4.3-dind
extends:
- .run_rules
- .monitor-in-grafana
@ -286,9 +286,9 @@ manifest_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
{% for IMAGE in singleImages %}
manifest_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
stage: manifest
image: docker:28.2.2
image: docker:29.4.3
services:
- docker:28.2.2-dind
- docker:29.4.3-dind
extends:
- .run_rules
- .monitor-in-grafana
@ -323,9 +323,9 @@ manifest_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
{% for IMAGE in multiImages %}
manifest_weekly_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
stage: manifest
image: docker:28.2.2
image: docker:29.4.3
services:
- docker:28.2.2-dind
- docker:29.4.3-dind
extends:
- .monitor-in-grafana
rules:
@ -350,9 +350,9 @@ manifest_weekly_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
{% for IMAGE in singleImages %}
manifest_weekly_{{ IMAGE.name1 }}_{{ IMAGE.name2 }}:
stage: manifest
image: docker:28.2.2
image: docker:29.4.3
services:
- docker:28.2.2-dind
- docker:29.4.3-dind
extends:
- .monitor-in-grafana
rules:

View file

@ -80,11 +80,9 @@ fi
# Manifest for multi pull and push for single arch
if [[ "${TYPE}" == "multi" ]]; then
docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
# Pull images from cache repo
docker pull ${ORG_NAME}/image-cache-private:x86_64-core-${NAME1}-${NAME2}-${PULL_BRANCH}-${CI_PIPELINE_ID}
docker pull ${ORG_NAME}/image-cache-private:aarch64-core-${NAME1}-${NAME2}-${PULL_BRANCH}-${CI_PIPELINE_ID}
docker pull --platform linux/arm64 ${ORG_NAME}/image-cache-private:aarch64-core-${NAME1}-${NAME2}-${PULL_BRANCH}-${CI_PIPELINE_ID}
# Conditionally Process Public Build
if [[ "${PUBLIC_BUILD}" == "true" ]]; then

View file

@ -176,6 +176,12 @@ for IP in "${IPS[@]}"; do
done
done
# Materialize docker config from env var if docker login was not run
if [ ! -f /root/.docker/config.json ] && [ -n "${DOCKER_AUTH_CONFIG:-}" ]; then
mkdir -p /root/.docker
printf '%s' "${DOCKER_AUTH_CONFIG}" > /root/.docker/config.json
fi
# Copy over docker auth
for IP in "${IPS[@]}"; do
scp \

View file

@ -98,7 +98,7 @@ fi
mkdir -p /var/run/pulse
WS_COMMIT_ID="f7efb82dc59a02d1b99e2e2b3c6d127dc548ba72"
WS_COMMIT_ID="f056f949e79a55217ec44c8fc4c79418ada0c05e"
WS_BRANCH="develop"
WS_COMMIT_ID_SHORT=$(echo "${WS_COMMIT_ID}" | cut -c1-6)

View file

@ -2,7 +2,7 @@
### every exit != 0 fails the script
set -e
COMMIT_ID="10efaf2e06feb2c1e3f7ee05978bbb9f0142c01b"
COMMIT_ID="d42f0ca30311beaed2c9833fbd71ba56ddae7ec6"
BRANCH="develop"
COMMIT_ID_SHORT=$(echo "${COMMIT_ID}" | cut -c1-6)
ARCH=$(arch | sed 's/aarch64/arm64/g' | sed 's/x86_64/amd64/g')

View file

@ -2,7 +2,7 @@
### every exit != 0 fails the script
set -e
COMMIT_ID="a69c61013e4c3f9600099cf940a33cab3e21f795"
COMMIT_ID="55a4cc861d77b6bbe736b23cc40669cf0a35706a"
BRANCH="develop"
COMMIT_ID_SHORT=$(echo "${COMMIT_ID}" | cut -c1-6)

View file

@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -ex
COMMIT_ID="0c56f4c9671a0ba895eb81984e1a037d676d366c"
COMMIT_ID="35f2831bf51b218de58f890cd16a8382c54b2215"
BRANCH="develop"
COMMIT_ID_SHORT=$(echo "${COMMIT_ID}" | cut -c1-6)

View file

@ -32,7 +32,7 @@ fi
# to the one watched by the printer service
sed -i -r -e "s:^(Out\s).*:\1/home/kasm-user/PDF:" /etc/cups/cups-pdf.conf
COMMIT_ID="7f560de30209f2fc9b59adb44430a80558c446ce"
COMMIT_ID="8a006be9c56e179daa80293fde4f37cfa8d600cb"
BRANCH="develop"
COMMIT_ID_SHORT=$(echo "${COMMIT_ID}" | cut -c1-6)

View file

@ -14,7 +14,7 @@ elif [ "${DISTRO}" == "opensuse" ]; then
zypper install -ny xhost
fi
COMMIT_ID="003984d8bc46847b87acbe8a877d43b586b9b793"
COMMIT_ID="65b1f19630c2e317b40613f150deaed97e64aa93"
BRANCH="develop"
COMMIT_ID_SHORT=$(echo "${COMMIT_ID}" | cut -c1-6)

View file

@ -16,7 +16,7 @@ else
fi
# Intall squid
SQUID_COMMIT='c45537169794a16029e06d7d456edb21b9ce7d12'
SQUID_COMMIT='eeb77407cf8ae952078520d8f4f231958a0ad98f'
if grep -q Focal /etc/os-release || grep -q bullseye /etc/os-release || [[ "${DISTRO}" == @(oracle8|almalinux8|rockylinux8) ]]; then
wget -qO- https://kasmweb-build-artifacts.s3.amazonaws.com/kasm-squid-builder/${SQUID_COMMIT}/output/kasm-squid-builder_ubuntu11_${ARCH}.tar.gz | tar -xzf - -C /
elif [[ "${DISTRO}" == "alpine" ]]; then
@ -75,7 +75,7 @@ sasldb_path: /etc/sasl2/memcached-sasldb2
EOL
COMMIT_ID="5fea98a35f1243102f8df2c4b156fcaf66861e7c"
COMMIT_ID="2472f2c1606244d311addc16dab436f5f56d5467"
BRANCH="develop"
COMMIT_ID_SHORT=$(echo "${COMMIT_ID}" | cut -c1-6)

View file

@ -8,7 +8,7 @@ elif [ "${DISTRO}" == "oracle8" ]; then
DISTRO=oracle
fi
COMMIT_ID="17df0c3a59f1ee1557ee91a0eaf8334e54cdc002"
COMMIT_ID="32c8f6f60395503152c55333bffb66df887bd4b5"
BRANCH="develop"
COMMIT_ID_SHORT=$(echo "${COMMIT_ID}" | cut -c1-6)