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.
note
Known issue
When creating a dev environment, CodeCanvas mounts directories for user data, including
/root, to store IDE indexes and data generated by user scripts. On the first environment start, CodeCanvas replaces/rootwith an empty directory (as no prior data exists). This behavior overwrites any data added to/rootduring the Docker image build stage (e.g.,.bashrcor app configurations). As a result, customizations or data defined in theDockerfileand stored in/rootare lost in the dev environment. To avoid this, add customizations like.bashrcin a lifecycle or warm-up script.
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
rootuser. 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
- 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:latestOther 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
If your registry requires authentication, add a connection to this registry in the namespace settings.
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_huborsome_registryDocker registry – a hostname of the remote Docker registry. For Docker Hub, it's
index.docker.ioAuthentication – 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-loginanddocker-credential-gcr.note
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'sdocker-credential-gcr.
Click Save.
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 myuserNote 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.