### Install .NET SDK

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs a specific version of the .NET SDK using the dotnet-install.sh script. It sets the DOTNET_ROOT and PATH environment variables for the installed SDK.

```dockerfile
# chunks/tool-dotnet/Dockerfile (variant "8" → DOTNET_VERSION=8.0.100)
ARG base
FROM ${base}
ARG DOTNET_VERSION
USER gitpod

RUN mkdir -p /home/gitpod/dotnet 
    && curl -fsSL https://dot.net/v1/dotnet-install.sh 
       | bash /dev/stdin --version ${DOTNET_VERSION} --install-dir /home/gitpod/dotnet

ENV DOTNET_ROOT=/home/gitpod/dotnet
ENV PATH=/home/gitpod/dotnet:$PATH
```

--------------------------------

### Install Docker CE with Compose and Dive

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs Docker CE, Docker Compose v2 plugin, and Dive for image analysis. This setup requires root privileges for installation and then switches to the gitpod user.

```dockerfile
# chunks/tool-docker/Dockerfile
ARG base
FROM ${base}
USER root

RUN curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
        | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg \
    && echo "deb [arch=$(dpkg --print-architecture) signed-by=...] \
        https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
        | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null \
    && apt update \
    && install-packages \
        docker-ce=5:28.2.2-1~ubuntu.22.04~jammy \
        docker-ce-cli=5:28.2.2-1~ubuntu.22.04~jammy \
        containerd.io docker-buildx-plugin

# Docker Compose v2 plugin
RUN curl -o /usr/local/bin/docker-compose -fsSL \
        https://github.com/docker/compose/releases/download/v2.39.2/docker-compose-linux-$(uname -m) \
    && chmod +x /usr/local/bin/docker-compose \
    && ln -s /usr/local/bin/docker-compose /usr/local/lib/docker/cli-plugins/docker-compose

# Dive — image layer analysis tool
RUN curl -o /tmp/dive.deb -fsSL \
        https://github.com/wagoodman/dive/releases/download/v0.12.0/dive_0.12.0_linux_amd64.deb \
    && apt install /tmp/dive.deb && rm /tmp/dive.deb

USER gitpod
```

--------------------------------

### Java Installation via SDKMAN

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs Java, Gradle, and Maven using SDKMAN, and configures Maven settings to use a persistent repository.

```dockerfile
# chunks/lang-java/Dockerfile
ARG base
FROM ${base}
ARG JAVA_VERSION
USER gitpod

RUN curl -fsSL "https://get.sdkman.io" | bash \
    && bash -c ". /home/gitpod/.sdkman/bin/sdkman-init.sh \
    && sdk install java ${JAVA_VERSION} \
    && sdk install java 17.0.17.fx-zulu \
    && sdk default java ${JAVA_VERSION} \
    && sdk install gradle \
    && sdk install maven 3.9.10 \
    && sdk flush archives && sdk flush temp \
    && mkdir /home/gitpod/.m2 \
    && printf '<settings>\n  <localRepository>/workspace/m2-repository/</localRepository>\n</settings>\n' \
       > /home/gitpod/.m2/settings.xml \
    && echo 'export SDKMAN_DIR="/home/gitpod/.sdkman"' >> /home/gitpod/.bashrc.d/99-java \
    && echo '[[ -s "/home/gitpod/.sdkman/bin/sdkman-init.sh" ]] && source "/home/gitpod/.sdkman/bin/sdkman-init.sh"' \
       >> /home/gitpod/.bashrc.d/99-java

ENV GRADLE_USER_HOME=/workspace/.gradle/

```

--------------------------------

### Install PostgreSQL 12

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs PostgreSQL 12 and its contrib package. It configures environment variables for data directory, database URL, and host address, and sets up scripts for starting and stopping the PostgreSQL server.

```dockerfile
ARG base
FROM ${base}

ENV PGWORKSPACE="/workspace/.pgsql"
ENV PGDATA="$PGWORKSPACE/data"
ENV DATABASE_URL="postgresql://gitpod@localhost"
ENV PGHOSTADDR="127.0.0.1"
ENV PGDATABASE="postgres"

RUN sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" 
        > /etc/apt/sources.list.d/pgdg.list'
    && wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
    && sudo install-packages postgresql-12 postgresql-contrib-12

ENV PATH="/usr/lib/postgresql/12/bin:$PATH"

RUN PGDATA="${PGDATA//\/workspace/$HOME}" 
    && mkdir -p ~/.pg_ctl/bin ~/.pg_ctl/sockets $PGDATA 
    && initdb -D $PGDATA 
    && printf '#!/bin/bash\npg_ctl -D $PGDATA -l ~/.pg_ctl/log -o "-k ~/.pg_ctl/sockets" start\n' 
       > ~/.pg_ctl/bin/pg_start 
    && printf '#!/bin/bash\npg_ctl -D $PGDATA -l ~/.pg_ctl/log -o "-k ~/.pg_ctl/sockets" stop\n' 
       > ~/.pg_ctl/bin/pg_stop 
    && chmod +x ~/.pg_ctl/bin/*

# Auto-start PostgreSQL on workspace open
COPY --chown=gitpod:gitpod postgresql-hook.bash $HOME/.bashrc.d/200-postgresql-launch
```

--------------------------------

### Install Ruby via RVM

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs Ruby using RVM (Ruby Version Manager). This script sets up RVM, installs a specified Ruby version, and configures the environment for use within Gitpod.

```dockerfile
ARG base
FROM ${base}
ARG RUBY_VERSION
USER gitpod

RUN curl -fsSL https://rvm.io/mpapis.asc | gpg --import -
    && curl -fsSL https://rvm.io/pkuczynski.asc | gpg --import -
    && curl -fsSL https://get.rvm.io | bash -s stable

ADD ./install.sh /tmp
RUN /tmp/install.sh $RUBY_VERSION

RUN echo '[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"' \
    >> /home/gitpod/.bashrc.d/70-ruby \
    && echo "rvm_gems_path=/workspace/.rvm" > ~/.rvmrc

ENV GEM_HOME=/workspace/.rvm
ENV PATH=/home/gitpod/.rvm/bin:$PATH
```

--------------------------------

### Install YugabyteDB

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs YugabyteDB, a distributed SQL database. It downloads, extracts, and installs the specified version, configures environment variables for ports and paths, and sets up an auto-start script for the workspace.

```dockerfile
# chunks/tool-yugabytedb/Dockerfile
ARG base
FROM ${base}
ARG YB_VERSION
ARG YB_BUILD
ARG YB_BIN_PATH=/usr/local/yugabyte

USER gitpod
RUN sudo mkdir -p $YB_BIN_PATH /var/ybdp 
    && sudo chown -R gitpod:gitpod /var/ybdp $YB_BIN_PATH

RUN curl -sSLo ./yugabyte.tar.gz 
        https://downloads.yugabyte.com/releases/${YB_VERSION}/yugabyte-${YB_VERSION}-b${YB_BUILD}-linux-x86_64.tar.gz 
    && tar -xvf yugabyte.tar.gz -C $YB_BIN_PATH --strip-components=1 
    && chmod +x $YB_BIN_PATH/bin/* && rm ./yugabyte.tar.gz

RUN ["/usr/local/yugabyte/bin/post_install.sh"]

ENV PATH="$YB_BIN_PATH/bin/:$PATH"
ENV YSQL_PORT=5433
ENV YCQL_PORT=9042
ENV WEB_PORT=7000
EXPOSE 5433 9042 7000 9000 13000 12000 15433

# Auto-start yugabyted on workspace open (skipped if .nopreload exists)
RUN echo "[[ -f \"
${GITPOD_REPO_ROOT}/.nopreload\" ]] || yugabyted start --base_dir=$STORE --listen=$HOST > /dev/null" 
    >> /home/gitpod/.bashrc.d/100-yugabyedb-launch
```

--------------------------------

### Go Installation via Tarball

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs a specific Go version from a tarball and configures GOPATH to persist across workspace restarts.

```dockerfile
# chunks/lang-go/Dockerfile
ARG base
FROM ${base}
ARG GO_VERSION
USER gitpod

ENV GO_VERSION=${GO_VERSION}
ENV GOPATH=$HOME/go-packages
ENV GOROOT=$HOME/go
ENV PATH=$GOROOT/bin:$GOPATH/bin:$PATH

RUN curl -fsSL https://dl.google.com/go/go$GO_VERSION.linux-amd64.tar.gz | tar xzs

# Install VS Code Go toolchain (gopls, dlv, golangci-lint, etc.)
RUN go install -v golang.org/x/tools/gopls@latest \
 && go install -v github.com/go-delve/delve/cmd/dlv@latest \
 && go install -v github.com/golangci/golangci-lint/cmd/golangci-lint@latest \
 && go install -v github.com/uudashr/gopkgs/cmd/gopkgs@v2 \
 && go clean -cache -modcache

# Redirect GOPATH to /workspace so it persists between workspace restarts
RUN printf '%s\n' 'export GOPATH=/workspace/go' 'export PATH=$GOPATH/bin:$PATH' \
    > $HOME/.bashrc.d/300-go

```

--------------------------------

### Install Bun JavaScript Runtime

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs a specific version of the Bun JavaScript runtime. It sets environment variables for the Bun installation directory and PATH, and copies a .bunfig.toml configuration file.

```dockerfile
# chunks/tool-bun/Dockerfile (variant "1" → BUN_VERSION=1.3.6)
ARG base
FROM ${base}
ARG BUN_VERSION

ENV BUN_INSTALL="${HOME}/.bun"
ENV PATH="${BUN_INSTALL}/bin:${PATH}"
ENV BUN_VERSION=${BUN_VERSION}

RUN curl -fsSL https://bun.sh/install | bash -s "bun-v${BUN_VERSION}"

COPY --chown=gitpod:gitpod .bunfig.toml "$HOME"
```

--------------------------------

### Install Homebrew (Linuxbrew)

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs Homebrew for Linux (Linuxbrew) in the user's home directory. It also sets up the PATH environment variable and disables automatic updates.

```dockerfile
# chunks/tool-brew/Dockerfile
ARG base
FROM ${base}
USER gitpod

RUN mkdir ~/.cache \
    && /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

ENV PATH=/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin/:$PATH
ENV HOMEBREW_NO_AUTO_UPDATE=1

RUN brew install cmake
```

--------------------------------

### Install Rust via rustup

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs Rust using rustup, including the `rust-analyzer`, `rust-src`, `rustfmt`, and `clippy` components. It also installs several useful Cargo subcommands.

```dockerfile
ARG base
FROM ${base}
ARG RUST_VERSION
USER gitpod

ENV PATH=$HOME/.cargo/bin:$PATH
ENV RUST_VERSION=${RUST_VERSION}

RUN curl -fsSL https://sh.rustup.rs | sh -s -- -y --no-modify-path \
        --default-toolchain ${RUST_VERSION} \
        -c rust-analyzer -c rust-src -c rustfmt -c clippy \
    && rustup set auto-self-update disable \
    && cargo install cargo-watch cargo-edit cargo-workspaces \
    && rm -rf "$HOME/.cargo/registry"

# Persist cargo registry across workspace restarts
ENV CARGO_HOME=/workspace/.cargo
ENV CARGO_INSTALL_ROOT=$HOME/.cargo
ENV RUSTUP_HOME=$HOME/.rustup
```

--------------------------------

### Install Nix Package Manager with Flakes and Direnv

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs Nix package manager, enabling flakes and direnv. It sets up necessary users and groups, configures Nix, and installs cachix and direnv via nix-env.

```dockerfile
# chunks/tool-nix/Dockerfile (variant: "2" → NIX_VERSION=2.19.2)
ARG base
FROM ${base}
ARG NIX_VERSION
ARG NIX_CONFIG=""
USER root

RUN addgroup --system nixbld 
    && adduser gitpod nixbld 
    && for i in $(seq 1 30); do useradd -ms /bin/bash nixbld$i && adduser nixbld$i nixbld; done 
    && mkdir -m 0755 /nix && chown gitpod /nix 
    && mkdir -p /etc/nix && echo 'sandbox = false' > /etc/nix/nix.conf

USER gitpod
RUN curl https://nixos.org/releases/nix/nix-$NIX_VERSION/install | sh
RUN echo '. /home/gitpod/.nix-profile/etc/profile.d/nix.sh' >> /home/gitpod/.bashrc.d/200-nix
RUN mkdir -p /home/gitpod/.config/nixpkgs 
    && echo '{ allowUnfree = true; }' >> /home/gitpod/.config/nixpkgs/config.nix

# Install cachix and direnv via nix
RUN . /home/gitpod/.nix-profile/etc/profile.d/nix.sh 
    && nix-env -iA cachix -f https://cachix.org/api/v1/install 
    && cachix use cachix 
    && nix-env -iA nixpkgs.direnv
```

--------------------------------

### Install Python via pyenv with Poetry and uv

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs Python using pyenv, along with Poetry for dependency management and uv for faster package operations. Ensure the base image supports the necessary build tools.

```dockerfile
ARG base
FROM ${base}
ARG PYTHON_VERSION
USER gitpod

ENV PATH="$HOME/.pyenv/bin:$HOME/.pyenv/shims:$PATH"
ENV PYENV_ROOT="$HOME/.pyenv"
ENV PIPENV_VENV_IN_PROJECT=true
ENV PYCHARM_PYTHON_PATH="$HOME/.pyenv/shims/python"

RUN sudo install-packages \
        python3-pip make build-essential libssl-dev zlib1g-dev \
        libbz2-dev libreadline-dev libsqlite3-dev llvm libffi-dev liblzma-dev \
    && git clone https://github.com/pyenv/pyenv.git ~/.pyenv \
    && git -C ~/.pyenv checkout 3441980e83bb1c5fdb2f1734ae4dab694d10ef71 \
    && pyenv install ${PYTHON_VERSION} \
    && pyenv global ${PYTHON_VERSION} \
    && pip install --no-cache-dir --upgrade \
        setuptools wheel virtualenv pipenv pylint rope flake8 \
        mypy autopep8 pydocstyle bandit notebook twine \
    && curl -sSL https://install.python-poetry.org | python \
    && curl -LsSf https://astral.sh/uv/install.sh | sh

COPY --chown=gitpod:gitpod python_hook.bash $HOME/.bashrc.d/60-python
```

--------------------------------

### Node.js Installation via NVM with Lazy Loading

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Installs Node.js using NVM, including global package managers like TypeScript and Yarn, with lazy loading configured for bash.

```dockerfile
# chunks/lang-node/Dockerfile
ARG base
FROM ${base}
ARG NODE_VERSION
USER gitpod

ENV NODE_VERSION=${NODE_VERSION}
ENV PNPM_HOME=/home/gitpod/.pnpm
ENV PATH=/home/gitpod/.nvm/versions/node/v${NODE_VERSION}/bin:/home/gitpod/.yarn/bin:${PNPM_HOME}:$PATH

# Install nvm, the requested Node version, then global package managers
RUN curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | PROFILE=/dev/null bash \
    && bash -c ". .nvm/nvm.sh \
        && nvm install v${NODE_VERSION} \
        && nvm alias default v${NODE_VERSION} \
        && npm install -g typescript yarn pnpm node-gyp" \
    && echo ". ~/.nvm/nvm-lazy.sh" >> /home/gitpod/.bashrc.d/50-node

```

--------------------------------

### GitHub Actions: Build and Release on Push to Main

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

This workflow triggers on pushes to the `main` branch. It performs linting, starts a BuildKit daemon, builds and combines Docker images using `dazzle`, and syncs them to Google Artifact Registry and Docker Hub.

```yaml
# .github/workflows/push-main.yml (key steps)
name: Build from Main
on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest-16-cores
    environment: "production"   # requires manual approval from reviewer
    env:
      DAZZLE_VERSION: 0.1.17
      BUILDKIT_VERSION: 0.12.3
      GAR_IMAGE_REGISTRY: europe-docker.pkg.dev

    steps:
      # 1. Lint (pre-commit, shellcheck, shfmt)
      - run: pre-commit run --all-files

      # 2. Start BuildKit daemon
      - run: |
          sudo buildkitd --oci-worker=true --oci-worker-net=host --debug --group docker &
          sudo su -c "while ! test -S /run/buildkit/buildkitd.sock; do sleep 0.1; done"

      # 3. Two-pass dazzle build → Google Artifact Registry
      - run: |
          dazzle build "${GAR_IMAGE_REGISTRY}/gitpod-artifacts/docker-dev/workspace-base-images" \
            --chunked-without-hash
          dazzle build "${GAR_IMAGE_REGISTRY}/gitpod-artifacts/docker-dev/workspace-base-images"

      # 4. Combine all images
      - run: |
          dazzle combine "${GAR_IMAGE_REGISTRY}/gitpod-artifacts/docker-dev/workspace-base-images" --all

      # 5. Tag with timestamp (format: YYYY-MM-DD-HH-MM-SS) and sync to Docker Hub
      #    Does NOT update the 'latest' tag
      - run: |
          echo "TIMESTAMP_TAG=$(date '+%Y-%m-%d-%H-%M-%S')" >> $GITHUB_ENV
          skopeo sync --src yaml --dest docker promote-images.yml registry.hub.docker.com/gitpod

```

--------------------------------

### Base Dockerfile for Gitpod Workspaces

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Sets up the common base layer for all Gitpod workspace images, including user creation, core tools, and git installation.

```dockerfile
# base/Dockerfile (condensed)
FROM buildpack-deps:jammy@sha256:2d01db7b05789751f60e2b82446e9fddf200c50a7d746b0c482899a54022b6e2

COPY install-packages upgrade-packages /usr/bin/

RUN yes | unminimize \
    && install-packages \
        zip unzip bash-completion build-essential ninja-build clang \
        htop jq less locales man-db nano ripgrep sudo stow \
        emacs-nox vim fish zsh rlwrap \
    && locale-gen en_US.UTF-8

ENV LANG=en_US.UTF-8

RUN upgrade-packages

# Install latest git + git-lfs
RUN add-apt-repository -y ppa:git-core/ppa \
    && curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | bash \
    && install-packages git git-lfs \
    && git lfs install --system --skip-repo

# Create gitpod user (UID 33333) with passwordless sudo
RUN useradd -l -u 33333 -G sudo -md /home/gitpod -s /bin/bash -p gitpod gitpod \
    && sed -i.bkp \
        -e '/Defaults\tuse_pty/d' \
        -e 's/%sudo\s\+ALL=(ALL\(:ALL\)\?)\s\+ALL/%sudo ALL=NOPASSWD:ALL/g' \
        /etc/sudoers \
    && mkdir /workspace && chown -hR gitpod:gitpod /workspace

USER gitpod
# Set up .bashrc.d/ sourcing — chunks drop shell init files here
RUN mkdir -p /home/gitpod/.bashrc.d && \
    echo 'for i in $(ls -A $HOME/.bashrc.d/); do source $HOME/.bashrc.d/$i; done' >> /home/gitpod/.bashrc

ENV PATH=$HOME/.local/bin:/usr/games:$PATH

```

--------------------------------

### Add New Tool Chunk to Gitpod Workspace

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

A step-by-step guide for adding a new tool chunk to the Gitpod workspace. This involves creating a Dockerfile, optionally a chunk.yaml for variants, a test file, and registering the new chunk in dazzle.yaml and configuration files.

```bash
# 1. Create the chunk directory following naming convention: category-name
mkdir chunks/tool-redis

# 2. Write the Dockerfile (always ARG base / FROM ${base}, end with USER gitpod)
cat > chunks/tool-redis/Dockerfile << 'EOF'
ARG base
FROM ${base}

USER root
ENV TRIGGER_REBUILD=1

RUN curl -fsSL https://packages.redis.io/gpg \
        | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg \
    && echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] \
        https://packages.redis.io/deb $(lsb_release -cs) main" \
        | sudo tee /etc/apt/sources.list.d/redis.list \
    && sudo install-packages redis

RUN echo "redis-server --daemonize yes" >> /home/gitpod/.bashrc.d/100-redis-launch

USER gitpod
EOF

# 3. (Optional) Add chunk.yaml if multiple versions are needed
cat > chunks/tool-redis/chunk.yaml << 'EOF'
variants:
  - name: "7"
    args:
      REDIS_VERSION: 7.2
EOF

# 4. Write a test file
cat > tests/tool-redis.yaml << 'EOF'
- desc: it should have redis-cli
  command: [redis-cli, --version]
  assert:
  - status == 0
  - stdout.indexOf("redis-cli") != -1
EOF

# 5. Register the combination in dazzle.yaml
cat >> dazzle.yaml << 'EOF'
    - name: redis
      ref:
      - base
      chunks:
        - tool-redis:7
EOF

# 6. Register the image in sync and promote configs
echo '    workspace-redis: "TIMESTAMP_TAG"' >> .github/promote-images.yml
echo '    workspace-redis: "TIMESTAMP_TAG"' >> .github/sync-containers.yml
```

--------------------------------

### Get Available Chunks with build-common.sh

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

This utility function lists all available chunk:variant combinations from the chunks/ directory. It handles chunks with and without chunk.yaml files.

```bash
function get_available_chunks() {
  for chunk in $(ls chunks); do
    local chunkYaml="chunks/${chunk}/chunk.yaml"
    if [[ -f "$chunkYaml" ]]; then
      for variant in $(yq e '.variants[].name' "$chunkYaml"); do
        echo "$chunk:$variant"
      done
    else
      echo "$chunk"
    fi
  done
}
```

--------------------------------

### Extending a Gitpod Base Image with a Custom Dockerfile

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Extend a Gitpod workspace image by adding custom tooling or dependencies. Ensure to manage user context, switching to root for installations and back to the 'gitpod' user for subsequent commands.

```dockerfile
# .gitpod.Dockerfile — extend the base image with extra tooling
FROM gitpod/workspace-python-3.13

# All subsequent RUN commands execute as root; switch back to gitpod at the end
USER root
RUN pip install --no-cache-dir fastapi uvicorn
USER gitpod
```

--------------------------------

### Java Version Test in Dazzle

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Tests if Java runs correctly and if a specific version (17.0.17) of OpenJDK and Maven are installed and functioning.

```yaml
- desc: it should run java
  command: [java -version]
  entrypoint: [bash, -i, -c]
  assert:
  - status == 0
  - stderr.indexOf("OpenJDK") != -1
- desc: it should have a functioning java 17 installed
  entrypoint: [env, GITPOD_REPO_ROOT=/workspace, bash, -ci]
  command: [sdk default java 17.0.17.fx-zulu && java -version && mvn -v]
  assert:
  - status == 0
  - stdout.indexOf("Apache Maven") != -1
```

--------------------------------

### Add Apt Repository Key and Source

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

Use GPG to securely unpack and store keyrings, then add them to apt sources. This is useful for adding unofficial repositories.

```bash
curl -fsSL https://apt.my-secure.org/my-unofficial-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/my-unofficial-repo.gpg.key
echo "deb [signed-by=/usr/share/keyrings/my-unofficial-repo.gpg.key] http://apt.my-secure.org/jammy/ \
my-unofficial-repo-toolchain main" | sudo tee /etc/apt/sources.list.d/my-unofficial-repo.list > /dev/null
```

--------------------------------

### Build All Images Locally

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

Execute this command to build all images locally using the default dazzle.yaml configuration. Be aware that this process can be resource-intensive and time-consuming.

```bash
./build-all.sh
```

--------------------------------

### Build Custom Docker Image

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Use this script to build a custom Docker image for your project. Ensure you have buildkitd and a local Docker registry running.

```bash
./build-combo.sh redis
```

--------------------------------

### Build All Chunks and Combinations

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Executes a full build process for all chunks and their combinations using the 'dazzle' tool. It performs a two-pass build for cache warming and content-addressed layers, then assembles all defined combinations.

```bash
# build-all.sh
#!/bin/bash
set -euo pipefail

REPO=localhost:5000/dazzle

dazzle build $REPO -v --chunked-without-hash   # pass 1: cache warming
dazzle build $REPO -v                           # pass 2: content-addressed
dazzle combine $REPO --all -v                   # assemble all combinations

# Usage:
./build-all.sh
# Pull a result:
docker pull localhost:5000/dazzle:full
docker pull localhost:5000/dazzle:python-3.13
```

--------------------------------

### Build Custom Workspace Image Combo

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

Use this script to build a specific workspace image combo. Replace 'full' with the desired combo name from dazzle.yaml.

```bash
./build-combo.sh full

```

--------------------------------

### Backup Dazzle Configuration with build-common.sh

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

This function backs up the current dazzle.yaml file to .dazzle.yaml.orig if it doesn't already exist. It's used to preserve the original configuration before modifications.

```bash
function save_original() {
  if [ ! -f .dazzle.yaml.orig ]; then
    cp dazzle.yaml .dazzle.yaml.orig
  fi
}
```

--------------------------------

### Using Gitpod Workspace Images in .gitpod.yml

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Specify a pre-built Gitpod workspace image as the base for your Gitpod environment. You can use a general image like 'gitpod/workspace-full' or pin to a specific language version. Alternatively, you can extend a base image with a custom Dockerfile.

```yaml
# .gitpod.yml — use the full pre-built image (Go, Java, Node, Python, Ruby, Rust, Docker, Brew, Nix, Nginx)
image: gitpod/workspace-full

# — OR — pin to a specific language image
image: gitpod/workspace-python-3.12

# — OR — extend with a custom Dockerfile
image:
  file: .gitpod.Dockerfile
```

--------------------------------

### Configure Gitpod Development Environment

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Defines the development environment for Gitpod, specifying the Dockerfile to use, ports to expose, and tasks to run on initialization. Includes recommended VS Code extensions.

```yaml
# .gitpod.yml
image:
  file: .gitpod.Dockerfile   # uses .gitpod.Dockerfile for the dev environment

ports:
  - port: 5000
    onOpen: ignore           # local Docker registry

tasks:
  - name: install pre-commit git hooks
    init: pre-commit install

  - name: start up buildkitd
    command: sudo /usr/bin/buildkitd --debug --config ./buildkitd.toml --group gitpod

  - name: start a local docker registry
    command: |
      mkdir -p /workspace/registry
      docker run -p 5000:5000 --name registry --rm \
        -v /workspace/registry:/var/lib/registry registry:2

  - name: dazzle build and test
    command: |
      gp ports await 5000
      REPO=localhost:5000/dazzle
      # Quick reference:
      # ./build-all.sh                              — build everything
      # ./build-chunk.sh -c lang-go -c lang-java:21 — build specific chunks
      # ./build-combo.sh full                       — build one combination

vscode:
  extensions:
    - ms-azuretools.vscode-docker
    - timonwong.shellcheck
```

--------------------------------

### Build Specific Combination with build-combo.sh

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

This script builds a single, specific combination of chunks by resolving its transitive dependencies. It's useful for building and testing a particular image variant.

```bash
./build-combo.sh postgres
```

```bash
./build-combo.sh java-21
```

```bash
docker pull localhost:5000/dazzle:java-21
```

```bash
# 1. Build the combo
./build-combo.sh full
# 2. Create test/ directory with Dockerfile referencing the local image
mkdir test
echo 'FROM localhost:5000/dazzle:full' > test/gitpod.Dockerfile
printf 'image:\n  file: gitpod.Dockerfile\n' > test/.gitpod.yml
# 3. Validate in a debug workspace
gp validate --workspace-folder="/workspace/workspace-images/test"
```

--------------------------------

### Configure Debug Workspace with Dockerfile

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

Define a custom workspace image using a Dockerfile in your test directory. The `.gitpod.yml` specifies the Dockerfile to use, and the Dockerfile itself extends a pre-built image.

```yaml
# test/.gitpod.yml
image:
    file: gitpod.Dockerfile

```

```Dockerfile
# test/gitpod.Dockerfile
FROM localhost:5000/dazzle:full # replace "full" with your own
# ... optionally, more steps here

```

--------------------------------

### Build Specific Combination

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

Build a single, specific image combination by providing its name as an argument to build-combo.sh. This command builds all necessary chunks for the specified combination.

```bash
./build-combo.sh postgresql
```

--------------------------------

### Build Specific Chunks with build-chunk.sh

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Use this script to build individual language or dependency chunks. You can specify multiple chunks to build them together.

```bash
./build-chunk.sh -c lang-go -c dep-cacert-update
```

```bash
./build-chunk.sh -c lang-go:1.24 -c lang-java:21
```

--------------------------------

### Pull Docker Image

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

Use this command to pull a specific image combination from the local registry. Replace 'combo' with the desired combination name like 'full', 'clojure', or 'postgres'.

```bash
docker pull localhost:5000/dazzle:combo
```

--------------------------------

### Pull Custom Workspace Image Locally

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

Pull the built workspace image to your local Docker registry. Ensure 'full' is replaced with your combo's name.

```bash
docker pull localhost:5000/dazzle:full

```

--------------------------------

### Pull Docker Image

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Pull a pre-built Docker image from a local registry. This is useful for testing images built locally before pushing them.

```bash
docker pull localhost:5000/dazzle:redis
```

--------------------------------

### GitHub Actions: Weekly Docker Hub Latest Tag Promotion

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

This workflow is scheduled to run weekly to promote images to the 'latest' tag on Docker Hub.

```yaml
# .github/workflows/dockerhub-release.yml

```

--------------------------------

### Publish Latest Images to Docker Hub

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

This workflow automates the copying of the ':latest' tag from Google Artifact Registry to Docker Hub for all tracked images. It uses skopeo for copying and a Slack action for notifications.

```yaml
name: Publish latest images to Docker Hub
on:
  workflow_dispatch:   # also supports manual trigger

jobs:
  promote-latest:
    steps:
      # Copies the :latest tag from GAR → Docker Hub for every tracked image
      - run: |
          IMAGES=$(cat .github/promote-images.yml \
            | yq '."europe-docker.pkg.dev/gitpod-artifacts/docker-dev"."images-by-tag-regex"|keys[]' -r)
          for IMAGE in $IMAGES; do
            skopeo copy --format=oci --retry-times=5 \
              docker://europe-docker.pkg.dev/gitpod-artifacts/docker-dev/$IMAGE:latest \
              docker://registry.hub.docker.com/gitpod/$IMAGE:latest
          done

      # Slack notification on success/failure
      - uses: slackapi/slack-github-action@...
        with:
          payload: '{"text": "The release was successful :rocket:"}'
```

--------------------------------

### Go Version Test in Dazzle

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Asserts that the 'go version' command runs successfully and its output contains 'go version'. Also checks if 'gopls version' runs successfully.

```yaml
- desc: it should run
  command: [go, version]
  assert:
  - stdout.indexOf("go version") != -1
  - status == 0
- desc: it should have gopls
  command: [gopls, version]
  assert:
  - status == 0
  - stdout.indexOf("gopls") != -1
```

--------------------------------

### Defining Image Combinations in dazzle.yaml

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

The 'dazzle.yaml' manifest defines how different 'chunks' (components like languages or tools) are combined to create final Docker images. You can define base images, full-featured images inheriting from others, or lightweight single-language images.

```yaml
# dazzle.yaml
combiner:
  combinations:
    # Minimal base: CA certificates, Docker daemon, Tailscale VPN
    - name: base
      chunks:
        - dep-cacert-update
        - tool-docker
        - tool-tailscale

    # Full-featured workspace (the default gitpod/workspace-full image)
    - name: full
      ref:
      - base                  # inherits base chunks
      chunks:
        - lang-c
        - lang-clojure
        - lang-go:1.24        # variant syntax: chunk-name:variant
        - lang-java:11
        - lang-node:24
        - lang-python:3.13
        - lang-ruby:3.2
        - lang-rust:1
        - tool-brew
        - tool-nginx
        - tool-nix:2

    # Lightweight single-language image
    - name: python-3.13
      ref:
      - base
      chunks:
        - lang-python:3.13

    # VNC image builds on top of full instead of base
    - name: full-vnc
      ref:
      - full
      chunks:
        - tool-chrome
        - tool-vnc

  # Environment variable merge strategy across chunk layers
  envvars:
    - name: PATH
      action: merge-unique   # PATH entries from all chunks are deduplicated and merged
    - name: HOME
      action: use-last
```

--------------------------------

### Build Specific Chunks

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

Build only the specified chunks using the build-chunk.sh script. This is useful for testing modifications to specific parts of the image build process.

```bash
./build-chunk.sh -c lang-c -c dep-cacert-update -c lang-go:1.17.5
```

--------------------------------

### Home Directory Ownership Test in Dazzle

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Ensures that there are no files in the /home/gitpod directory that are not owned by the 'gitpod' user and group.

```yaml
- desc: it should not have root-owned files in the home directory
  command: [find /home/gitpod -not "(" -user gitpod -and -group gitpod ")" -print -quit]
  entrypoint: [bash, -i, -c]
  assert:
  - status == 0
  - stdout.trim().length == 0
```

--------------------------------

### Validate Workspace Changes

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

Use `gp validate` to open a debug workspace for testing your changes. Specify the workspace folder containing your test configuration.

```bash
gp validate --workspace-folder="/workspace/workspace-images/test"

```

--------------------------------

### Add Bashrc.d Script

Source: https://github.com/gitpod-io/workspace-images/blob/main/CONTRIBUTING.md

When creating a new rc file, place it in the .bashrc.d directory. All files in this directory are sourced for a bash session.

```bash
RUN echo "/etc/mydb/mydb-bashrc-launch.sh" >> /home/gitpod/.bashrc.d/100-my-service-launch.sh
```

--------------------------------

### Build Specific Chunks

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Selectively builds one or more named chunks using the 'dazzle' tool. It ignores unused chunks and then performs a two-pass build process similar to the full build.

```bash
# build-chunk.sh
# Selectively builds one or more named chunks, ignoring all others. Uses `dazzle project ignore` to suppress unused chunks, then invokes the two-pass dazzle build.
```

--------------------------------

### Update Go Patch Versions in chunk.yaml

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

This script automatically updates the Go patch versions in `chunks/lang-go/chunk.yaml`. It fetches the latest stable Go versions from the actions/go-versions repository and uses `sed` to apply the updates.

```javascript
// .autofix/fixers/update-lang-go.js
const os = require('os');

exports.register = async (fixers) => {
  // Fetch the Go versions manifest from the actions/go-versions repo
  const response = await fetch(
    "https://raw.githubusercontent.com/actions/go-versions/main/versions-manifest.json"
  );
  const data = await response.json();

  // Build sed substitutions: for each stable major.minor, find the latest patch
  const patchVersionReplacements = {};
  for (const version of data.filter(v => v.stable).flatMap(v => v.version).reverse()) {
    const match = version.match(/^(\d+\.\d+)\.(\d+)$/);
    if (!match) continue;
    const segments = version.split('.');
    const prefix = segments.slice(0, -1).join('\\.');
    patchVersionReplacements[prefix + '\\\[0-9][0-9]*'] = version;
  }

  // Register a fixer that rewrites GO_VERSION in chunk.yaml
  fixers[0].push({
    id: 'update-lang-go',
    cmd: Object.keys(patchVersionReplacements).map(pattern =>
      `sed ${os.type() === 'Darwin' ? '-i "" -E' : '-i -e'} \n"s/\\(GO_VERSION.*\\)${pattern}/\\1${patchVersionReplacements[pattern]}/g
```

--------------------------------

### Declaring Chunk Variants in chunk.yaml

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

A 'chunk.yaml' file within a chunk's directory defines named variants, mapping to Docker 'ARG' values. This allows a single Dockerfile to produce multiple versioned images for that chunk. Chunks without this file are treated as single, unversioned units.

```yaml
# chunks/lang-java/chunk.yaml
variants:
  - name: "11"
    args:
      JAVA_VERSION: 11.0.29.fx-zulu
  - name: "17"
    args:
      JAVA_VERSION: 17.0.17.fx-zulu
  - name: "21"
    args:
      JAVA_VERSION: 21.0.9.fx-zulu
  - name: "23"
    args:
      JAVA_VERSION: 23.0.2.fx-zulu
  - name: "25"
    args:
      JAVA_VERSION: 25.fx-zulu

# chunks/lang-node/chunk.yaml
variants:
  - name: "18"
    args:
      NODE_VERSION: 18.20.8
  - name: "22"
    args:
      NODE_VERSION: 22.22.0
  - name: "24"
    args:
      NODE_VERSION: 24.13.0
  - name: "25"
    args:
      NODE_VERSION: 25.6.1
```

--------------------------------

### Node.js Version and Package Manager Tests in Dazzle

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

Verifies Node.js version (v24 or v25), and the presence and functionality of Yarn and pnpm package managers.

```yaml
- desc: it should run node
  command: [node --version]
  entrypoint: [bash, -i, -c]
  assert:
  - status == 0
  - stdout.indexOf("v24") != -1 || stdout.indexOf("v25") != -1
- desc: it should have yarn
  command: [yarn --version]
  entrypoint: [bash, -i, -c]
  assert:
  - status == 0
- desc: it should have pnpm
  command: [pnpm --version]
  entrypoint: [bash, -i, -c]
  assert:
  - status == 0
```

--------------------------------

### Update Node.js Minor Versions in chunk.yaml

Source: https://context7.com/gitpod-io/workspace-images/llms.txt

This script updates Node.js minor versions in `chunks/lang-node/chunk.yaml`. It queries available Node.js versions using `nvm ls-remote` and applies updates via `sed`.

```javascript
// .autofix/fixers/update-lang-node.js
const os = require('os');
const { execSync } = require('child_process');
const util = require('util');
const exec = util.promisify(require('child_process').exec);

exports.register = async (fixers) => {
  // Query available Node.js versions via nvm
  const { stdout } = await exec('bash -lc ". ~/.nvm/nvm.sh && nvm ls-remote --no-colors"');

  const minorVersionReplacements = {};
  for (const line of stdout.split('\n')) {
    const match = line.trim().match(/^[->]*\s*([a-z1-9\.]+-)?v(\d+\.)(\d+\.\d+)\s*.*$/);
    if (!match || match[2] === '0.') continue;
    const prefix = match[1] ? match[1] + 'v' : '';
    const pattern = (prefix + match[2]).replace(/\./g, '\\.') + '[0-9][0-9]*\\.[0-9][0-9]*';
    minorVersionReplacements[pattern] = prefix + match[2] + match[3];
  }

  fixers[0].push({
    id: 'upgrade-lang-node',
    cmd: Object.keys(minorVersionReplacements).map(pattern =>
      `sed ${os.type() === 'Darwin' ? '-i "" -E' : '-i -e'} \n"s/\\(NODE_VERSION.*\\)${pattern}/\\1${minorVersionReplacements[pattern]}/g
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.