Workspace

Workspace is a remote development solution built on cloud-native principles, supporting remote connections via web and VSCode clients.

Design Principles
One-Click Creation of Development Environment
Customizing the Development Environment
Customizing the Creation Process
Customizing Resource Specifications
Custom Startup Events
Custom Availability Time
Custom Cloud Native Development Launch Button

# Design Principles

Declarative: Based on the Docker ecosystem, Dockerfile declares the development environment and manages it alongside the code.
Fast Startup: Even for large repositories, it is possible to prepare the code and environment within seconds.
On-Demand Usage: Development resources are acquired as needed and quickly reclaimed during idle times to avoid resource waste

# One-Click Creation of Development Environment

You can click the "Workspace" button in the branch page to create a development environment with a single click. No configuration is required, and it will directly open a default development environment using cnbcool/default-dev-env:latest as the base image.

# Customizing the Development Environment

If you want to start a custom development environment when clicking the "Workspace" button on the branch page, you can add a .ide/Dockerfile file in the root directory of the repository. In the Dockerfile, you can freely customize the development environment. When starting the development environment, a custom image will be built using the .ide/Dockerfile as the base image.

Note: In the default pipeline for launching the development environment, both the default image and .ide/Dockerfile are configured. If .ide/Dockerfile does not exist or fails to build, the default image will be used as the base image for the development environment. If the launched environment does not meet expectations, you can check the build logs in the prepare phase to see whether .ide/Dockerfile was successfully built.

# .ide/Dockerfile
FROM node:20

# Install additional software as needed
# RUN apt-get update && apt-get install -y git

# Install code-server and commonly used VSCode extensions
RUN curl -fsSL https://code-server.dev/install.sh | sh \
  && code-server --install-extension redhat.vscode-yaml \
  && code-server --install-extension dbaeumer.vscode-eslint \
  && code-server --install-extension waderyan.gitblame \
  && code-server --install-extension mhutchie.git-graph \
  && code-server --install-extension donjayamanne.githistory \
  && code-server --install-extension tencent-cloud.coding-copilot \
  && echo done

# Install SSH service to support Remote-SSH access to the development environment from the VSCode client
RUN apt-get update && apt-get install -y wget unzip openssh-server

# Specify character set to support inputting Chinese characters in the command line
# (choose the appropriate character set as needed)
ENV LANG C.UTF-8
ENV LANGUAGE C.UTF-8

# Customizing the Creation Process

If you want to use a custom YAML pipeline configuration when clicking the "Workspace" button on the branch page, you can add a .cnb.yml file in the root directory of the repository and add the following configuration:

# .cnb.yml
$:
  # VSCode event: specifically for starting remote development from the page
  vscode:
    - docker:
        # Use a custom image as the development environment
        image: node:20
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al

# Customizing Resource Specifications

You can declare the required development resources using runner.cpus, with a maximum of 64 cores and memory equal to cpus x 2(GB).

# .cnb.yml
$:
  vscode:
    - runner:
        cpus: 64
      docker:
        build: .ide/Dockerfile
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al

# Custom Startup Events

By using .cnb.yml, you can declare the automatic creation of a development environment when specific events are triggered. The recommended trigger events are:

vscode: Create a development environment when you click the Launch Cloud Native Development button on the repository page
branch.create: Create a development environment when creating a branch
api_trigger: Custom event triggers the creation of a development environment
web_trigger: Web page custom event triggers the creation of a development environment

# .cnb.yml
# Match all branches
(**):
  # Create a development environment when creating a branch
  branch.create:
    - name: vscode
      services:
        # Declare the use of the vscode service
        - vscode
      docker:
        # Custom development environment
        build: .ide/Dockerfile
      stages:
        - name: Execute custom script
          script:
            - npm install
            - npm run start

# Custom Availability Time

The default availability time for Cloud Native Development is after the pipeline preparation (prepare) stage is completed (code-server code service starts during the preparation stage) and before the stages task is executed.

If you want to enter the development environment after executing certain tasks, that is, delay the time to enter the development environment, you can use the vscode:go built-in task. With this task, after starting Cloud Native Development, the loading page will delay entering the Cloud Native Development entry selection page. You can only enter the entry selection page after the vscode:go task is executed.

Note that using the vscode:go task will increase the waiting time. You can put tasks that must be executed before entering the development environment before vscode:go, and tasks that are executed after entering the development environment after vscode:go. If there is no task that must be executed before entering the development environment, there is no need to use vscode:go.

When the stages task execution fails, whether the remote development ends:

Using vscode:go: If the task before vscode:go fails, the development environment will be destroyed.
Using vscode:go: If the task after vscode:go fails, the development environment will not be destroyed.
Not using vscode:go: If the stages task execution fails, the development environment will not be destroyed.

# Custom Cloud Native Development Launch Button

You can configure the cloud native development launch button as needed, such as: button name, button description, whether the button is disabled, and the number of CPU cores to launch.

Add a .cnb/settings.yml file in the repository.

# .cnb/settings.yml
workspace:
  # Customize the cloud-native development launch button on the branch page/repository homepage
  launch:
    # The following parameters are all optional
    button:
      # Button name, default is: Cloud Native Development
      name: Cloud Native Launch
      description: Launch remote development to quickly experience the cloud environment
    # Number of CPU cores, default is: 8. Only effective for the default template; if there is a custom cloud-native development launch pipeline, this configuration is invalid
    cpus: 8
    # Whether to disable the button, default is: false (not disabled). true means disabled
    disabled: false
    # After clicking the cloud-native development button, the environment will automatically open the WebIDE upon creation (regardless of whether client-side connection for remote development is supported).
    # If OpenSSH is not installed in the development environment (only WebIDE is supported): Regardless of whether this parameter is configured as true or false, the WebIDE will automatically open upon environment creation.
    autoOpenWebIDE: true

Note: If the file fails to parse or exceeds the size limit, the configuration will not be applied.

Tips and Tricks →