Custom Workspace Base Images

The default base image for workspaces already ships with many useful tools and libraries. However, you can create your own custom base images. One reason to customize base images is packages that are not available through Nix but need to be installed via apt.

The Codesphere OMS CLI provides a convenient way to start building your own custom base images.

Prerequisites:

1. On your host, install Docker and the Buildx plugin (if not already installed): sudo apt install docker.io docker-buildx
2. Install the OMS CLI as described at https://github.com/codesphere-cloud/oms
3. Use the extend baseimage command in OMS CLI, see oms beta extend baseimage -h
4. This command extracts the default base image from the Codesphere installer bundle, loads it into your local Docker image cache, and generates a Dockerfile that you can extend.
5. Confirm with docker image ls that the base image (ghcr.io/codesphere-cloud/codesphere-monorepo/workspace-agent-VERSION) is available locally.
6. Edit the generated Dockerfile to add your custom dependencies.
7. As a best practice, place the Dockerfile into a subdirectory, e.g. ./docker. This ensures that in the following docker build command, only the necessary files are sent to the Docker daemon.
8. Retrieve the base image tag from the Dockerfile, e.g. codesphere-1-67-1-4dd9b346cc, and use the same tag for your custom image.
9. Build the custom image with the following command: docker buildx build -f ./docker/custom.Dockerfile -t workspace-agent-24.04-mycorp:<TAG_TO_USE> --load ./docker
10. Tag and push the image to your own registry with the same tag as the original image: docker tag workspace-agent-24.04-mycorp:<TAG_TO_USE> <YOUR_REGISTRY_URL>/workspace-agent-24.04-mycorp:<TAG_TO_USE> docker login <YOUR_REGISTRY_URL> # if not already logged in docker push <YOUR_REGISTRY_URL>/workspace-agent-24.04-mycorp:<TAG_TO_USE>