Skip to main content

Configured Development Mode

You can manage a DevMode configuration of the workload in Nocalhost IDE or create the configuration manually.

Manage DevMode Configurations#

By IDE Plugin#

Nocalhost will generate a runtime configuration stored in the memory. This configuration can be used across IDEs in your local computer after being saved.

In general, when using the Nocalhost IDE plugin, the plugin automatically updates the DevMode configurations according to your operation. No manual configuration is required.


These runtime configurations created by the Nocalhost only save in your local computer. If you change the computer or delete the .nh folder, you will lose the current configurations.

Expand the cluster inspector and select a workload. There is a little gear icon at the end of the workload. This icon has two different states:

  • Does not have configuration, Nocalhost will generate a new configuration after you click.
  • Has a configuration, Nocalhost will load the existing configuration after you click.
Edit workload dev configuration in VS Code
Take effect

All changes will not take effect until the next time you enter development mode.

Manually Create Configurations#

If you want to have persisted DevMode configuration to use on a different computer or share with others, you can add a .nocalhost folder under your source code root directory and create a config.yaml file within the folder.

You can read this configuration example to set up your configuration.

Configuration Priority#

If you have added .nocalhost/config.yaml to your source code root directory, Nocalhost will use the configuration in the config.yaml to replace the one set by the plugin.

If you use the IDE plugin to open the configuration, this configuration will become read-only. The plugin will also guide the user to modify the configuration directly in the local file, not the one opened by the plugin.

Example: Using and open local configuration#

# Tips: This configuration is an in-memory replica of the local file: # # '~/whatever/details/.nocalhost/config.yaml'# # You should modify your configuration in local file, and the modification will# take effect immediately. (Dev modification will take effect the next time you enter the DevMode)## In addition, if you want to configure multi-services in the same config.yaml, or use# the Server-version of Nocalhost, you can also configure under the definition # of the application, such as:# name: detailsserviceType: deploymentcontainers:- name: container_name  dev:    image:    shell: bash    workDir: /home/nocalhost-dev

Development Mode Configurations#

All configurations for development mode are in services[*].container[*].dev section.

application:  name: foo-app  ....
  services:    - name: foo-workload-01                 # string    |  required  | Name of workload      serviceType: deployment               # string    |  required  | The Kubernetes Workloads type corresponding to this service      ...      containers:                           # struct    |  optional          - name: container-01                # string    |  required  | Container name          dev:            gitUrl: ""                      # string    |  required  | Git repository url            image: ""                       # string    |  required  | DevContainer image repository url            shell: "/bin/sh"                # string    |  optional  | The default shell of DevContainer            workDir: /home/nocalhost-dev    # string    |  optional  | The work directory of DevContainer            storageClass: "cbs"             # string    |  optional  | Storage of persistence volume            resources: null                 # struct    |  optional  | Specify resources requests and limits for DevContainer, same format to Kubernetes's resources            persistentVolumeDirs: []        # string[]  |  optional  | Dirs to be persisted in DevContainer            command: ...                    # string[]  |  optional  | Build command of the workload            debug: ...                      # struct    |  optional  | Specify debug parameter            useDevContainer: false          # string    |  optional  | Use .dev-container of VSCode to specify DevContainer Image            sync: ...                       # struct    |  optional  | Specify file synchronization when enter development mode            env: ...                        # struct    |  optional  | Specify development mode environment parameters            envFrom: null                   # struct    |  optional  | Specify development mode environment parameters by files            portForward: []                 # string    |  optional  | Ports to be forwarded to local when enter devMode


Set the source code repository URL of the workload.

containers:  - name: container-01    dev:      gitURL:
Clone Source Code

Nocalhost will use git clone command to clone the source code. Please make sure you have Git installed on your local computer.


Specify the development image (DevImage) to replace the image of the DevContainer when entering development mode.


image accepts image name or URL. If you enter the image name, Nocalhost will pull the specified image from Docker Hub. Or you can use your own private image library, e.g.

Example: Set the image for DevConatiner#

containers:  - name: container-01    dev:      ...      image:

Configure the default shell of DevContainer, you can use bin/sh or shell within DevContainer.


containers:  - name: container-01    dev:      ...      shell: "/bin/sh"      ...


Used to indicate the working directory in the remote container after entering the DevMode and the directory where the synchronized files are stored. By default, /home/nocalhost-dev will be used.

Example: Setting up the Work Directory#

containers:  - name: container-01    dev:      ...      workDir: /home/nocalhost-dev      ...


Optionally specify how much of each resource a DevContainer needs and limits. This is similar to Kubernetes resources management

Example: Setting up DevContainer's requests and limits#

containers:  - name: container-01    dev:      ...      resources:        limits:          cpu: "1"          memory: 1Gi        requests:          cpu: "0.5"          memory: 512Mi      ...


Set the storage class name for a DevContainer

Example: Setting up storage class name#

containers:  - name: container-01    dev:      ...      storageClass: "storage-class-name"      ...


Directories that need to be persisted in DevContainer

Example: Setting up the persistent directories#

containers:  - name: container-01    dev:      ...      persistentVolumeDirs:         - path: "/root"             # string  | required  | DIR that need to be persisted          capacity: 100Gi           # string  | optional  | Capacity of the DIR.


containers:  - name: container-01    dev:      ...      command:        run:  [""]                # string  | optional  | Run command of the workload        debug:  [""]              # string  | optional  | Debug command of the workload


Configure the remote debugging port for the DevContainer.

When using Nocalhost's remote debugging feature, the plugin will connect to the specified port to debug the remote workload.

containers:  - name: container-01    dev:      ...      debug:        remoteDebugPort: 5050     # integer | optional  | Specify the remote debug pot      ...


Use .dev-container of VS Code to specify DevImage.

Example: Setting up the remote debugging port#

containers:  - name: container-01    dev:      ...      useDevContainer: false      # string  | optional  | Use .dev-container of VSCode to specify DevImage      ...


Files synchronization configurations in DevMode.

containers:  - name: container-01    dev:      ...      sync:        type: send                  # select    | optional  | The synchronization file mode of the workload                 filePattern: ["."]        # string[]  | optional  | List of files and directories to be synchronized to DevConatiner          ignoreFilePattern: ["."]  # string[]  | optional  | List of ignored files and directories to be synchronized to DevConatiner      ...

Read more to learn how to configure file synchronization

dev.env and dev.envFrom#

Nocalhost supports injecting the preset environment variables to a container in development mode. You can inject these variables by input the values or import the file.

nocalhost-dep Needed

You need to have nocalhost-dep installed for this configuration to take effect. Please refer to Nocalhost Dep for more details.

Example: Setting up inject environment variable#


containers:  dev:    ...    env:       - name: DEBUG        value: ${DEBUG:-true}      - name: DOMAIN        value: ""


  • These variables will be injected into the container when entering development mode
  • These variables will take effect after the entered development mode
Duplicate Configs

If both env and envFrom configure at the same time, Nocalhost will merge the configurations, and the duplicate parts are subject to env configs.


The portForward section defines which localhost port should be forwarded to the remote port of the selected container.

containers:  dev:    ...    portForward:      - 38228:80

Read more to learn how to configure port-forwarding for development mode