Single/Double Container Mode

About 517 wordsAbout 2 min

Cloud-native development supports two launch modes:

Single Container Mode: Development environment and code-server run in the same container
Double Container Mode: Development environment and code-server run in separate containers, with shared workspace (/workspace) directory

Development Environment: A container specified via .ide/Dockerfile or a custom image, or the default CNB container environment, which includes user-installed or pre-installed software.

Single Container Mode

Single container mode is recommended. The following methods start in single container mode:

Starting with Default Configuration

When no configuration is set (i.e., no startup pipeline and .ide/Dockerfile), the development environment starts with default configuration. The default environment has code-server and ssh installed, so it uses single container mode, supporting both WebIDE and VSCode remote development.

See Default Development Environment for details.

Starting with Custom Configuration

When a startup pipeline or .ide/Dockerfile is configured, and the custom image or .ide/Dockerfile has code-server installed, single container mode is used.

The following three methods all start in single container mode (all launch images have code-server installed):

Double Container Mode

When the development environment container doesn't have code-server installed, the system will start an additional code-server container to provide code service — this is double container mode. The workspace (/workspace) directories are shared between the two containers.

The following two methods will start in double container mode:

.cnb.yml
# Method 1: use a Docker image without code-server
$:
  vscode:
    - docker:
        image: node:22
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al

.ide/Dockerfile
# Method 2: use a custom Dockerfile without code-server
FROM node:20

RUN apt-get update && apt-get install -y git wget unzip openssh-server

ENV LANG C.UTF-8
ENV LANGUAGE C.UTF-8

Both methods share the same principle: the dev container lacks code-server, so the system automatically adds a code-server container, forming the double container mode.

Double Container Mode — Cross-Container Terminal

In double container mode, accessing WebIDE or VSCode actually connects to the code-server container. To access the development environment container, you can use the cross-container terminal provided in WebIDE or VSCode — the default terminal is a cross-container terminal named CNB.

If the development environment container doesn't support git, switch to a non-CNB terminal to use the built-in code-server terminal for git operations.

Double Container Mode — Plugin Capability Limitations

In double container mode, VSCode plugins are installed in the code-server container and may not be able to access the development environment container (such as Debug and other features that require access to it).

Single/Double Container Mode​