mirror of
https://github.com/kasmtech/workspaces-images.git
synced 2026-07-17 16:46:08 +00:00
87 lines
4.2 KiB
Markdown
87 lines
4.2 KiB
Markdown
# 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](https://gitlab.com/kasm-technologies/internal/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
|
|
|
|
```bash
|
|
# 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`:
|
|
```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.
|