Skip to content

CLAUDE.md

Latest commit

 

History

History
87 lines (65 loc) · 4.18 KB

CLAUDE.md

File metadata and controls

87 lines (65 loc) · 4.18 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Workspaces Images is the catalog of pre-built Kasm workspace images (applications and full desktops) published to DockerHub and Quay. Each image layers application-specific install scripts on top of a base image from workspaces-core-images.

Repository Layout

dockerfile-kasm-<name>      # Flat Dockerfile per image at repo root
src/
  ubuntu/install/<app>/     # Install scripts for Ubuntu-based images
  common/                   # Shared scripts used across distros
  alpine/, opensuse/, ...   # Distro-specific install scripts
ci-scripts/
  template-vars.yaml        # Image manifest: name, base, dockerfile, changeFiles, runset
  template-gitlab.py        # Generates gitlab-ci.yml from template-vars.yaml
  build.sh                  # Builds + pushes to cache registry
  test.sh                   # Runs post-build smoke tests via AWS/curl
  manifest.sh               # Creates and pushes multi-arch manifests
  weekly-manifest.sh        # Scheduled rolling-tag manifest updates

Building Images Locally

# Build a single image (run from repo root)
sudo docker build -t kasmweb/firefox:dev -f dockerfile-kasm-firefox .

# Run it locally
sudo docker run --rm -it --shm-size=512m -p 6901:6901 -e VNC_PW=password kasmweb/firefox:dev
# Access via browser: https://<IP>:6901  (user: kasm_user, password: password)

The BASE_TAG build arg controls which core image tag is pulled (default: develop). Override with --build-arg BASE_TAG=<tag> to build against a specific core release.

Adding a New Image

  1. Create dockerfile-kasm-<name> at the repo root. Use an existing dockerfile as a template — the pattern is:

    • Set ARG BASE_IMAGE / ARG BASE_TAG and FROM kasmweb/$BASE_IMAGE:$BASE_TAG
    • Add install scripts under src/<distro>/install/<name>/
    • Copy scripts into $INST_SCRIPTS, run them, then delete them
    • Fix ownership with chown 1000:0 $HOME and run set_user_permission.sh
    • End with USER 1000

  2. Add an entry to ci-scripts/template-vars.yaml:

    - name: <name>
  runset: set-a          # or set-b — distributes load across CI run sets
  singleapp: true        # false for full desktop images
  base: core-ubuntu-jammy  # or core-ubuntu-noble, core-debian-bookworm, etc.
  dockerfile: dockerfile-kasm-<name>
  changeFiles:
    - dockerfile-kasm-<name>
    - src/ubuntu/install/<name>/**

  3. The CI pipeline is generated — do not edit gitlab-ci.yml directly; edit template-vars.yaml and template-gitlab.py instead.

CI/CD

The pipeline runs in two stages:

  1. template — template-gitlab.py reads template-vars.yaml and generates gitlab-ci.yml as a CI artifact.
  2. run — triggers a child pipeline from the generated gitlab-ci.yml.

Key CI variables (set in GitLab or pipeline triggers):

  • BASE_TAG — core image tag to build against (default: develop)
  • USE_PRIVATE_IMAGES — set to 1 to pull from private registry
  • KASM_RELEASE — release version string for test installer
  • RUN_SET — restrict CI to set-a or set-b image subsets
  • MIRROR_ORG_NAME — DockerHub org for mirror pushes (default: kasmtech)

On develop and release/* branches, images are pushed publicly to DockerHub and Quay. Feature branches push only to an internal cache registry tagged <arch>-<name>-<branch>-<pipeline_id>.

Image Naming Conventions

  • Single-app images use singleapp: true and strip the XFCE panel for a focused UI.
  • Desktop images (singleapp: false) ship the full XFCE desktop environment.
  • Base image names follow core-<distro>-<codename> (e.g. core-ubuntu-jammy, core-ubuntu-noble, core-debian-bookworm).
  • Published tags: kasmweb/<name>:<branch> for branch builds, kasmweb/<name>:<version> for releases.

Distro Support

Install scripts are organized under src/<distro>/install/<app>/. Ubuntu scripts (jammy/noble) are the most common. When adding support for a new distro, add scripts under the appropriate src/<distro>/ subtree and reference them in the dockerfile.