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 the root user. To run the container as a non-root user, you need to create a custom image.
Major updates of CodeCanvas may introduce changes to the default image. If this causes issues, system administrators can force using a specific version of the default image. 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
				

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

Find the namespace.
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) Follow the instructions to create a cloud policy for the role.
    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 dev environment under non-root user

Due to security reasons, you might want to run a dev environment under a non-root user. To do this, you need to use a custom Docker image with a non-root user specified in the Dockerfile. If your project requires some tools to be installed with apt-get, you should install them before switching to the non-root user.

Here is an example of a Dockerfile that creates an image with a non-root user:

				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 -g 1001 mygroup && \
					useradd -m -u 1001 -g mygroup myuser

				# Switch to the non-root user
				USER myuser
			

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

Last modified: 22 January 2025