Container Image

Dev environments in CodeCanvas run in Docker containers. The toolchains, runtimes, and other software required for development are defined in a Docker image. When creating a template, you can either use a default image provided by CodeCanvas or specify a custom one.

Default Docker image

If you don't specify a Docker image, CodeCanvas will use the default one. The default image is based on Ubuntu OS and includes Git, curl, Docker, Docker Compose, Kubernetes, Google Cloud support, Open JDK, Python, PHP, .NET SDK, Ruby, Go, Node.js, npm, yarn, and other tools.

You can find the default image in the public JetBrains Docker registry: public.jetbrains.space/p/codecanvas/packages/container/releases/dev-container-default

Important notes:

The default image uses a non-root user codecanvas (UID 22222) belonging to the codecanvas group (GID 22222). To run commands in the container that require root privileges, use the sudo command.
Before CodeCanvas 2025.2, the default image used the root user. If you upgrade from an earlier version, make sure your scripts don't assume root access. Use sudo when needed.
Major updates of CodeCanvas may change the default image. If this causes issues, system administrators can pin a specific image version. Learn more

Use custom Docker image

Image requirements

OS: any Linux distribution that includes GLIBC 2.27 or later. The OS must maintain compliance with the FHS (Filesystem Hierarchy Standard). For example, CentOS 7+, Debian 9+, Ubuntu 20.04+.
Tools: Git, OpenSSH, util-linux, Docker (if you need Docker for your project).
If you are going to use a JetBrains IDE in the dev environment, ensure the image meets the IntelliJ IDEA requirements for remote development.

The minimal recommended Dockerfile:

					FROM ubuntu:latest

					# Install necessary tools
					RUN apt-get update && apt-get install -y \
						openssh-server \
						util-linux \
						git \
						docker.io \
						sudo

					# Create a group and a non-root user
					RUN groupadd --gid 22222 codecanvas && \
						useradd codecanvas \
						--create-home \
						--home-dir /home/codecanvas \
						--shell /bin/bash \
						--uid 22222 \
						--gid 22222 \
						--no-log-init \
						--groups sudo \
						--no-user-group && \
						echo "codecanvas ALL=(ALL) NOPASSWD:ALL" >>/etc/sudoers.d/nopasswd

					# Add the user to the docker group
					RUN usermod -aG docker codecanvas

					# Set the default user
					USER codecanvas
					ENV HOME=/home/codecanvas
				

To specify the URL of your custom image, use the Advanced | Dev container image section of a dev environment template.

You can use any image from any private or public registry, including Docker Hub, GitHub Container Registry, and others.

Docker Hub
If you host your image on Docker Hub, you can specify only the image name. For example, mycompany/myimage:latest
Other registries
If you use a registry different from Docker Hub, specify the full URL of the image. For example, registry.example.com/mycompany/myimage:latest

Private registries

If your registry requires authentication, add a connection to this registry in the namespace settings.

To connect a Docker registry

Select Namespaces in the header navigation, then select the namespace you need.
In the sidebar namespace menu, click Settings, then select Docker Registry Connections.
Click New connection and specify connection settings:
- Key – a unique connection name that you will use to reference this connection in jobs, e.g., docker_hub or some_registry
- Docker registry – a hostname of the remote Docker registry. For Docker Hub, it's index.docker.io
- Authentication – the type of authentication to use.
  - Username/Password – specify the Username and Password (token) for the registry.
  - Use credential helper – use this option for authentication with a credential helper.
    How to use credential helpers
    Instead of using the credentials directly, you can securely store them in a platform-specific service. To retrieve the credentials, the worker will use a helper program that communicates with the service. Currently, CodeCanvas supports credential helpers for registries hosted in AWS ECR (Amazon Elastic Container Registry) and GCR (Google Container Registry). For this purpose, the worker container has two built-in credential helpers: docker-credential-ecr-login and docker-credential-gcr.
    You can also use a custom credential helper. In this case, you should use a custom worker image with the helper installed. The image is defined in the CodeCanvas Helm chart.
    Using a credential helper requires some preparation:
    (System admin) Create a role with the permissions to read the required Docker registry:
    AWS EKS – IAM role
    Google GKE – Google service account
    (System admin) Create a cloud policy for the role. Learn how to do this
    When creating or editing the dev environment template, select the created cloud policy in the Cloud policy field.
    Once the required cloud policy is set for the template, you can use a credential helper for the Docker registry: Select Use credential helper and specify the Credential helper name. For AWS ECR, it's docker-credential-ecr-login, for GCR, it's docker-credential-gcr.
Click Save.

Run in rootless mode

If your security policy doesn't allow using sudo, you can still run dev environments under the required codecanvas user without root privileges.

Here's an example Dockerfile that disables sudo and root tools:

				FROM ubuntu:latest

				# Install necessary tools
				RUN apt-get update && apt-get install -y \
					openssh-server \
					util-linux \
					git

				# Create a group and a non-root user
				RUN groupadd --gid 22222 codecanvas && \
					useradd codecanvas \
					--create-home \
					--home-dir /home/codecanvas \
					--shell /bin/bash \
					--uid 22222 \
					--gid 22222 \
					--no-log-init \
					--no-user-group

				# Set the default user
				USER codecanvas
				ENV HOME=/home/codecanvas
			

Note that if your project requires Docker in a dev environment, you'll need to install Docker in rootless mode via the Dockerfile and run the daemon from a lifecycle script. Learn more about running Docker in rootless mode in the official Docker documentation.

02 June 2025