JetBrains CodeCanvas 2024.1 Help

Get Started as Namespace Administrator

A namespace is an organizational entity (a logic container) that groups related resources, e.g., Git repositories, dev environment templates with all environment settings (container image, environment variables, IDE settings), etc. A namespace can represent a project or a group of projects your company is working on. Learn more about namespaces

A namespace administrator is a CodeCanvas user with the Namespace Admin role in a namespace. By default, only a system administrator can create a namespace and assign you this role. Nonetheless, your company might have a different policy – the system administrator can delegate the namespace creation to ordinary CodeCanvas users.

As a namespace administrator, you should prepare it for other users: connect the required Git repositories, prepare a dev environment image, configure warmup, etc. Let's get your namespace up and running smoothly!

1. Create a namespace

If your company policy allows you to create namespaces, you can do it yourself. Otherwise, ask your system administrator to create a namespace for you and proceed to the next step.

  1. On the sidebar, select Namespaces.

  2. Click New namespace and specify the namespace name and other settings.

    Create namespace

Learn more about namespaces.

2. Connect a Git repository

CodeCanvas doesn't provide Git hosting, so you should connect the project with a Git repository hosted elsewhere. When a dev environment is created, it will receive a clone of the connected repository.

In our example, let's connect a GitHub repository. In the documentation, you can also find instructions for GitLab, Bitbucket, and other Git hosting services.

  1. In CodeCanvas, on the sidebar menu, select Namespaces, then the namespace you need.

  2. On the sidebar namespace menu, select Repositories.

  3. Click New connection.

    Connect a Git repository
  4. Provide repository Name and other settings:

    • Remote repository URL   – the SSH or HTTPS URL of the repository, e.g., git@github.com:MyCompany/my-project.git or https://github.com/MyCompany/my-project.git

    • Repository web URL   – the URL of the remote repository's web interface. CodeCanvas will show this link in the repository list. For example, this can be a link to the project's README file on GitHub.

    • Read restrictions – leave All users or choose Only selected users and specify the users allowed to read the repository contents. In this case, this list must be synced with the list of allowed users on the Git server.

  5. If the repository doesn't require authentication, leave Anonymous in Authentication. Otherwise, choose either SSH (for SSH authentication) or Password (for HTTPS authentication).

    For SSH authentication, you need to provide an SSH key pair. CodeCanvas will use the private key only to clone the repository into dev environments. Users will be required to specify their own SSH key to pull from and push to the repository.

    1. First, generate a new SSH key pair for CodeCanvas. On your local machine, run:

      ssh-keygen -t ed25519

      During key pair generation, you can additionally protect the private key with a passphrase. Finally, your current directory will contain a pair of files, e.g., mykey (private key) and mykey.pub (public key).

    2. On your remote Git server, add the public key to the list of authorized keys.

      On GitHub, go to the repository | Settings | Deploy keys and click Add deploy key. Paste the contents of the public key file (mykey.pub) into the Key field and click Add key.

      Git key
    3. In CodeCanvas, in the Authentication field, select SSH and provide the private key file (mykey) and the passphrase (if you've specified it during key pair generation).

      Connect Git repo

    In CodeCanvas, in the Authentication field, select Password and provide the username and password for the remote Git server.

    For GitHub, you can generate a personal access token and use it as the password. CodeCanvas will use this token only to clone the repository into dev environments. Users will be required to specify their own GitHub credentials to pull from and push to the repository.

    1. On GitHub, go to your profile | Settings | Developer settings | Personal access tokens | Fine-grained tokens and click Generate new token.

      GitHub token
    2. In Repository access, select Only select repositories and select the repository you want to connect.

    3. In Permissions, in Contents, select Read-only.

    4. Click Generate token.

    5. Copy the token and specify it in CodeCanvas as a repository Password and your GitHub username as Username.

  6. You can first Test connection, and if everything is OK, click Connect. After this, the repository will appear in the Repositories list.

3. Create a dev environment template

A dev environment template is a set of settings that define how a dev environment should be created. For example, it can specify the base image (toolchains, runtimes, etc.), the resources allocated to the dev environment, Git repositories and branches to clone, and other settings. When a user creates a new dev environment, they're asked to select a template.

  1. In CodeCanvas, on the sidebar menu, select Namespaces, then the namespace you need.

  2. On the namespace sidebar menu, select Templates and click New template.

    New template
  3. Provide the template Name and General Settings:

    • Repository   – the Git repository to clone into user dev environments. Here, you can select one of the repositories you've connected in the previous step or add a new repository connection.

    • Instance type   – defines the resources allocated to user dev environments. The list of available instance types is configured by the system administrator. Learn more

    • IDE and IDE version   – the IDE and its version that will be used to open your project in user dev environments. The list of available IDEs and versions is configured by the system administrator. Learn more

  4. Click Next and provide other settings:

    • Project settings

      • Checkout branch – the branch to clone from the repository. If you want to clone the default branch, leave it empty.

      • Project root   – the path relative to the project root directory that will be opened in the user IDE. This path will be used as the working directory.

      • Environment variables   – additional environment variables available in the user dev environment. Here, you can click Add variable and provide its Name and Value. Don't use this setting for providing sensitive data like passwords or tokens!

    • Performance and costs

      Here, you can configure the Warm-up and Standby pool features. This is an optional step, but it can significantly improve the startup performance of user dev environments. We will cover them in the next steps.

    • Access

      Specify who is allowed to create dev environments based on this template: Only selected users or All users (conditions apply). Users outside this list won't see this template in their JetBrains Gateway client.

      Important! This setting must be aligned with the read restrictions of the connected repository. Users who aren't in the Read restrictions and Access lists won't be able to create dev environments.

    • Lifecycle scripts

      Here, you can provide shell scripts that will run during the dev environment lifecycle. For example, you can use them to install IDE plugins, configure some automation, etc. For details, refer to Lifecycle Scripts.

    • Personal parameters

      If your project requires some sensitive data like passwords or tokens, you can require users to provide them when creating a dev environment. Inside a dev environment, these parameters will be available as environment variables or files.

      For example, you can create an environment variable DB_PASSWORD and mark it as a required parameter. When a user creates a dev environment, they will be asked to link a corresponding secret from their personal storage to this parameter.

      Learn more about personal parameters.

      Personal parameters
    • Advanced

      • SSH access – choose this option if you want users to be able to access the dev environment via SSH. If you use a custom dev environment image, ensure it provides an SSH server like sshd.

      • VM Options – additional JVM options for the user IDE. Probably, the most important option for IDE performance is -Xmx, which defines the maximum memory size allocated for the user IDE. The default value is calculated automatically based on the amount of memory available in a dev environment.

      • Dev container image   – a full name of a Docker image that will be used to create user dev environments. Make sure it provides all the necessary toolchains and runtimes for your project. If you don't specify an image, CodeCanvas will use the default image that includes almost all the popular toolchains and runtimes.

        If your Docker registry requires authentication, you can provide the credentials in the namespaces Settings | Docker Registry Connections page.

        Registry connections
      • Cloud policy – if the system administrator has configured seamless access to cloud resources via the cloud policies, you can select a policy here.

  5. Click Create. After this, the template will appear in the template list.

(Optional, boosts startup) Configure warm-up

You can significantly reduce the initial IDE startup time by pre-creating warm-up snapshots. These snapshots can contain IDE indexes, project dependencies, and other data. When a user creates a dev environment, CodeCanvas will mount the warm-up snapshot to the dev environment, letting skip the project import, initial indexing, and build of the project.

When configuring the warm-up, you can specify the following settings:

  • Instance type – the resources allocated to the dev environment that will be used for creating the warm-up snapshot.

  • Create project indexes   – if enabled, CodeCanvas will create IDE indexes for the project in the warm-up snapshot. Note that indexes created by different IDE versions might be incompatible. Generally, the compatibility is preserved among builds of a major version, e.g., 2023.3.X.

  • Script path   – a path to the shell script that will run during the warm-up snapshot creation. You can use this script to install project dependencies, build the project, and so on. Note that the script is run before the IDE indexes are created. To make this work, you should first create a script file in the repository connected to the template.

  • Parameters – environment variables that will be available in the warm-up. Use them to provide sensitive data to the warm-up environment like user credentials or access tokens. Learn more

  • Execution timeout (minutes)   – CodeCanvas stops the warm-up and considers it failed if it takes longer than the specified time.

  • Cron triggers   – a list of cron triggers that define when the warm-up snapshot should be created. For example, you can create a snapshot every day at 3 AM, i.e., 0 3 * * *

If you want to create a warm-up snapshot without waiting for the cron trigger, click New warm-up snapshot on the Warm-up Snapshots page. This page also shows the list of created snapshots and their status.

Warm-up snapshots

(Optional, boosts startup) Configure standby pool

Even if you use warm-up snapshots for the fast IDE startup, it still takes some time for CodeCanvas to allocate resources for a new dev environment, create a volume from the warm-up snapshot, and so on. The IDE also needs some time to load the project and become responsive. Standby pool eliminates this delay by pre-creating dev environments and keeping them running. When a user opens a dev environment, CodeCanvas takes a ready dev environment from the pool. Right after the dev environment is taken, CodeCanvas creates a new one to preserve the specified number of available dev environments in the standby pool.

To use the standby pool, select the Standby pool option and specify the following settings:

  • Size   – the number of dev environments in the standby pool. For example, if a user takes a dev environment from the standby pool, CodeCanvas will instantly start creating a new one to keep the pool size.

  • Stop dev environments after initialization   – this option can help you save compute resources while keeping a decent dev environment startup time. If enabled, CodeCanvas starts dev environments in the standby pool and waits until the IDEs are ready to use. After that, CodeCanvas unmounts volumes and stops the dev environments. When a user accesses a new dev environment, CodeCanvas mounts the volume from the standby pool to the dev environment and starts it. This way, users need to wait for the creation of the environment but not for the IDE initialization phase. The IDE is ready to use immediately.

  • Cron schedule and Cron schedule timezone   – a schedule (in the specified timezone) that defines active hours for the standby pool to keep the specified size.

What next

Now, your namespace is ready for other users. Note that in CodeCanvas, users don't work directly with namespaces – in their JetBrains Gateway client, they see only dev environment templates. Based on the templates you've created, users can create dev environments and start working on the project. How? Learn this in the Get Started as Dev Environment User guide.

Last modified: 17 May 2024