Installation to Amazon EKS

1. Set up PostgreSQL databases

CodeCanvas requires two PostgreSQL databases: one for the CodeCanvas application and another for the Jump server.

1. Install PostgreSQL server (version 12.2 – 15.5). The server must be accessible from the CodeCanvas application cluster, e.g., you can create a pod with the server in the same cluster.

2. Create dedicated databases for the CodeCanvas application and the Jump server.

3. Ensure that the database server is up and running before proceeding with the installation.

2. Create AWS S3 bucket

Create an AWS S3 bucket to store CodeCanvas and user data.

3. Prepare CodeCanvas application cluster

1. Amazon EKS cluster

   Set up an Amazon EKS cluster for the CodeCanvas application. Make sure the cluster meets the requirements from the table below.

   Requirement	Description
   Helm	Version 3.6.0 or later
   Kubernetes (K8s)	Version 1.29 or later
   Cluster nodes	At least four nodes with Linux OS (x86_64), recommended min resources: 4 CPU cores and 8GB memory

2. Namespace

   Create a dedicated namespace for the CodeCanvas application (replace NAMESPACE_PLACEHOLDER with an actual namespace name):

   kubectl create namespace NAMESPACE_PLACEHOLDER

3. Ingress controller

   Install an Ingress controller compatible with your Kubernetes setup. In our example, we use an ingress-nginx controller.

4. Prepare dev environment cluster

1. Amazon EKS cluster

   Set up a Kubernetes cluster for dev environments. Make sure the cluster meets the requirements from the table below. Depending on your needs, you can create multiple dev environment clusters (the requirements are the same for all clusters). To reduce latency for end users, we recommend deploying the dev environment cluster in the same region as the potential dev environment users.

   Requirement	Description
   Helm	Version 3.6.0 or later
   Kubernetes (K8s)	Version 1.29 or later
   Cluster nodes	Sufficient nodes to run dev environments, each with Linux OS (Ubuntu, x86_64), recommended min resources: 4 CPU cores and 8GB memory

2. Namespace

   Create a dedicated namespace for the dev environment cluster (replace NAMESPACE_PLACEHOLDER with an actual namespace name):

   kubectl create namespace NAMESPACE_PLACEHOLDER

3. CSI driver

   Install the ebs.csi.aws.com CSI driver in the cluster. For installation instructions, refer to the AWS documentation.

4. CSI snapshot controller

   Install the CSI snapshot controller in the cluster to enable Kubernetes snapshot manipulation. You can install it using the AWS-managed add-on or manually.

5. Storage class

   Create a storage class for persistent volumes. You can use our recommended storage class configuration below.

   apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: ebs-sc-gp3-16000iops-750mgbps mountOptions: - debug parameters: type: gp3 iops: "16000" throughput: "750" provisioner: ebs.csi.aws.com allowVolumeExpansion: true reclaimPolicy: Delete volumeBindingMode: Immediate

6. Volume snapshot class

   Create a volume snapshot class for managing snapshots. You can use our recommended volume snapshot class configuration below.

   apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: csi-aws-vsc driver: ebs.csi.aws.com deletionPolicy: Delete

7. CSI snapshot validation webhook

   Install an add-on to the CSI driver that implements K8s snapshot validation. For the instructions, refer to the K8s documentation. Tested with v6.2.2.

5. Configure DNS and TLS

1. Domain name

   Register a domain name for the CodeCanvas instance, e.g., codecanvas.example.com.

2. DNS zones

   Install ExternalDNS in the CodeCanvas application cluster to manage DNS records.

3. TLS certificates

   Install cert-manager in the CodeCanvas application cluster to manage TLS certificates issued by Let's Encrypt.

4. Subdomains

   Configure subdomains for the CodeCanvas application components. The configuration in custom.values.yaml supposes the following DNS domain naming scheme:

   • EXTERNAL_DOMAIN_PLACEHOLDER – the main domain for the CodeCanvas application that serves the main administrative UI and REST API. For example, codecanvas.example.com

   • computeservice.EXTERNAL_DOMAIN_PLACEHOLDER – the subdomain that serves the compute-service REST API. It is an internal domain customarily accessed only by dev environment pods.

   • gateway.EXTERNAL_DOMAIN_PLACEHOLDER – serves the gateway-relay service. It is an external domain accessed by user IDE clients.

   • jump.EXTERNAL_DOMAIN_PLACEHOLDER – serves the REST API of the jump-server service. It is an internal domain customarily accessed only by dev environment pods and the server.

   • ssh.EXTERNAL_DOMAIN_PLACEHOLDER – serves the SSH service of the jump-server service. It is an external domain accessed by user IDE clients.

6. Set up IAM roles and permissions

To grant CodeCanvas access to a storage bucket in AWS, you can use either static credentials or IAM roles for service accounts (IRSA). We recommend using IRSA.

Configure the IRSA role for the CodeCanvas application service account. CodeCanvas requires write permission to the bucket. For details on how to set up IRSA, refer to the AWS documentation.

7. (Optional) Configure the SMTP server

CodeCanvas uses the SMTP server to send various emails to users, for example, invitation links during the user creation, email verification, and other notifications. If you want to enable this functionality, ensure you have an SMTP server accessible from the CodeCanvas application cluster.

1. Create custom.values.yaml

Create a custom.values.yaml and copy the snippet below to it. You will replace placeholders with actual values in the next steps.

2. Assign an AWS IRSA role to the CodeCanvas application

In custom.values.yaml, replace CODECANVAS_IRSA_ARN with the actual ARN of the AWS IRSA role that the CodeCanvas application should use.

3. Specify external domain

In custom.values.yaml, replace EXTERNAL_DOMAIN_PLACEHOLDER with the domain name you've registered for your CodeCanvas instance.

4. Set up cert-manager

In custom.values.yaml, replace CERT_MANAGER_NAME_PLACEHOLDER with the name of cert-manager used in your cluster.

5. Specify database settings

The CodeCanvas installation implies that you use an external PostgreSQL database. Though you can use any PostgreSQL database, we recommend using Amazon RDS.

6. Specify Jump server database settings

The Jump server also uses an external PostgreSQL database.

7. Specify object storage settings

This installation implies that you use an AWS S3 bucket for storing user data.

You should authorize CodeCanvas to access your S3 object storage in one of two ways: using static credentials or IAM roles for service accounts (IRSA). We recommend using IRSA.

8. Create a master secret

The CodeCanvas application keeps user secrets (e.g., credentials to external services) in the database in an encrypted form. The master secret is used to encrypt and decrypt these data.

1. Generate the master secret by running

   openssl rand -base64 32

2. In custom.values.yaml, replace MASTER_SECRET_PLACEHOLDER with the generated value.

9. Configure the system administrator account

The system administrator account will be used for logging in to and configuring CodeCanvas after the installation.

1. In custom.values.yaml, replace ADMIN_USERNAME_PLACEHOLDER and ADMIN_PASSWORD_PLACEHOLDER with desired administrator credentials.

2. Replace ADMIN_EMAIL_PLACEHOLDER with an email address for receiving administrator notifications from CodeCanvas.

10. Specify the storage class

In custom.values.yaml, replace WORKER_STORAGE_CLASS_NAME_PLACEHOLDER with the storage class name you've created.

11. Specify the volume snapshot class name

In custom.values.yaml, replace WORKER_VOLUME_SNAPSHOT_CLASS_NAME_PLACEHOLDER with the volume snapshot class name you've created.

12. Create gateway-relay keys

The Relay server acts as an intermediary between JetBrains Gateway on a user machine and the dev environment. The communication between them is secured with SSL/TLS. To establish a secure connection, the gateway and the Relay server must have a pair of keys which you need to generate. The public key is shared with the Relay server. The private key is then used by JetBrains Gateway to authenticate dev environments in the Relay server.

1. Generate a private key:

   openssl ecparam -name prime256v1 -genkey -noout -out gateway-ec-prime256v1-priv-key.pem
   cat gateway-ec-prime256v1-priv-key.pem

2. In custom.values.yaml, replace GATEWAY_PRIVATE_KEY_PLACEHOLDER with the generated key value.

3. Generate a public key:

   openssl ec -in gateway-ec-prime256v1-priv-key.pem -pubout > gateway-ec-prime256v1-pub-key.pem
   cat gateway-ec-prime256v1-pub-key.pem

4. In custom.values.yaml, replace GATEWAY_PUBLIC_KEY_PLACEHOLDER with the generated key value.

5. Delete the gateway-ec-prime256v1-priv-key.pem and gateway-ec-prime256v1-pub-key.pem files.

13. Create Jump server keys

The Jump server acts as an intermediate server that provides indirect SSH connections between a user machine (SSH client, VS Code in the remote mode, etc.) and the SSH daemon in a dev environment. The SSH connection requires a pair of keys which you need to generate. The public key is shared with the Jump server. The private key is then used by the SSH client to authenticate in the Jump server.

1. Generate a private key:

   openssl ecparam -name prime256v1 -genkey -noout -out jump-ec-prime256v1-priv-key.pem
   cat jump-ec-prime256v1-priv-key.pem

2. In custom.values.yaml, replace JUMP_PRIVATE_KEY_PLACEHOLDER with the generated key value.

3. Generate a public key:

   openssl ec -in jump-ec-prime256v1-priv-key.pem -pubout > jump-ec-prime256v1-pub-key.pem
   cat jump-ec-prime256v1-pub-key.pem

4. In custom.values.yaml, replace JUMP_PUBLIC_KEY_PLACEHOLDER with the generated key value.

5. Delete the jump-ec-prime256v1-priv-key.pem and jump-ec-prime256v1-pub-key.pem files.

6. Generate a private host key:

   openssl genrsa -traditional 2048 2>/dev/null

7. In custom.values.yaml, replace JUMP_HOST_PRIVATE_KEY_PLACEHOLDER with the generated key value.

14. Specify the Ingress class

In custom.values.yaml, replace INGRESS_CLASS_PLACEHOLDER with the Ingress class used for the CodeCanvas Kubernetes cluster.

15. Specify the Kubernetes service account for the CodeCanvas pod

Suppose you've set up a Service account in the application cluster and prefer the service account name to be independent of the Helm release name. In that case, you may want to specify a particular name for the Kubernetes service account that the CodeCanvas Helm chart will create. To do this, in custom.values.yaml, replace CODECANVAS_KSA_NAME with the desired name.

16. (Optional) Configure Sysbox container runtime

By default, CodeCanvas runs worker containers in the --privileged mode (the containers have root privileges on the host node). If you want to avoid this due to security reasons, install Sysbox Container Runtime as described here.

17. Install the CodeCanvas chart

Run:

Here:

• NAMESPACE_PLACEHOLDER is your Kubernetes namespace

• codecanvas is the Helm release name. You can change it if needed

1. Verify the state of CodeCanvas pods

Run:

All pods must be in the Running state. On average, it takes about 2 minutes after deployment for a pod to become active.

If the pods are not Running, try finding the cause by running:

and

2. Verify domain name resolution

The domain name must resolve to the Ingress load balancer. You can check this by running:

The output must not contain any errors.

3. Check the CodeCanvas application

Open your CodeCanvas instance in a browser. When logging in to CodeCanvas, use the administrator credentials provided during the installation.