Customize the Docker extension

The Docker extension includes several Visual Studio Code tasks to control the behavior of Docker build and run, and form the basis of container startup for debugging.

The tasks allow for a great deal of control and customization. The final configuration is a combination of general defaults, platform-specific defaults (such as Node.js, Python, or .NET), and user input. User input takes precedence when it conflicts with defaults.

All common features of Visual Studio Code tasks (for example, grouping tasks into compound tasks) are supported by Docker extension tasks. For more information on common task features and properties, see the Visual Studio Code custom task documentation.

Docker build task

The docker-build task builds Docker images using the Docker command line (CLI). The task can be used by itself, or as part of a chain of tasks to run and/or debug an application within a Docker container.

The most important configuration settings for the docker-build task are dockerBuild and platform:

• The dockerBuild object specifies parameters for the Docker build command. Values specified by this object are applied directly to Docker build CLI invocation.
• The platform property is a hint that changes how the docker-build task determines Docker build defaults.

See property reference for full list of all task properties.

Platform support

While the docker-build task in tasks.json can be used to build any Docker image, the extension has explicit support (and simplified configuration) for Node.js, Python, and .NET Core.

Node.js (docker-build)

Minimal configuration using defaults

A Node.js based Docker image with no specific platform options can just set the platform property to node:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Node Image",
      "type": "docker-build",
      "platform": "node"
    }
  ]
}

Platform defaults

For Node.js Docker images, the docker-build task infers the following options:

Python (docker-build)

Minimal configuration using defaults

A Python based Docker image with no specific platform options can just set the platform property to python:

{
  "tasks": [
    {
      "type": "docker-build",
      "label": "docker-build",
      "platform": "python"
    }
  ]
}

Platform defaults

For Python Docker images, the docker-build task infers the following options:

.NET (docker-build)

Minimal configuration using defaults

When you build a .NET-based Docker image, you can omit the platform property and just set the netCore object (platform is implicitly set to netcore when netCore object is present). Note that appProject is a required property:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Node Image",
      "type": "docker-build",
      "netCore": {
        "appProject": "${workspaceFolder}/project.csproj"
      }
    }
  ]
}

Platform defaults

For .NET-based images, the docker-build task infers the following options:

Build task reference

Here are all properties available for configuring docker-build task. All properties are optional unless indicated otherwise.

dockerBuild object properties

node object properties (docker-build task)

netCore object properties (docker-build task)

Docker run task

The docker-run task in tasks.json creates and starts a Docker container using the Docker command line (CLI). The task can be used by itself, or as part of a chain of tasks to debug an application within a Docker container.

The most important configuration settings for the docker-run task are dockerRun and platform:

• The dockerRun object specifies parameters for the Docker run command. Values specified by this object are applied directly to Docker run CLI invocation.
• The platform property is a hint that changes how the docker-run task determines Docker run defaults.

See property reference for full list of all task properties.

Docker run platform support

While the docker-run task can be used to run any Docker image, the extension has explicit support (and simplified configuration) for Node.js, Python, and .NET.

Node.js (docker-run)

Minimal configuration using defaults

A Node.js based Docker image with no specific platform options can just set the platform property to node.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run Node Image",
      "node": "docker-run",
      "platform": "node"
    }
  ]
}

Platform defaults

For Node.js-based Docker images, the docker-run task infers the following options:

Python (docker-run)

When building a Python-based Docker image, you can omit the platform property and just set the python object (platform is implicitly set to python when python object is present)

Minimal configuration for Django Apps

{
  "type": "docker-run",
  "label": "docker-run: debug",
  "dependsOn": ["docker-build"],
  "python": {
    "args": ["runserver", "0.0.0.0:8000", "--nothreading", "--noreload"],
    "file": "path_to/manage.py"
  }
}

Minimal configuration for Flask Apps

{
  "type": "docker-run",
  "label": "docker-run: debug",
  "dependsOn": ["docker-build"],
  "dockerRun": {
    "env": {
      "FLASK_APP": "path_to/flask_entry_point.py"
    }
  },
  "python": {
    "args": ["run", "--no-debugger", "--no-reload", "--host", "0.0.0.0", "--port", "5000"],
    "module": "flask"
  }
}

Minimal configuration for General Apps

{
  "type": "docker-run",
  "label": "docker-run: debug",
  "dependsOn": ["docker-build"],
  "python": {
    "file": "path_to/app_entry_point.py"
  }
}

Platform defaults

For Python-based Docker images, the docker-run task infers the following options:

.NET (docker-run)

Minimal configuration using defaults

When building a .NET-based Docker image, you can omit the platform property and just set the netCore object (platform is implicitly set to netcore when netCore object is present). Note that appProject is a required property:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run .NET Core Image",
      "type": "docker-run",
      "netCore": {
        "appProject": "${workspaceFolder}/project.csproj"
      }
    }
  ]
}

Platform defaults

For .NET-based images, the docker-run task infers the following options:

Run task reference

Here are all properties available for configuring docker-run task. All properties are optional unless indicated otherwise.

dockerRun object properties

ports object properties

extraHosts object properties

volumes object properties

node object properties (docker-run task)

python object properties (docker-run task)

netCore object properties (docker-run task)

Docker Compose task

The docker-compose task in tasks.json creates and starts Docker containers using the Docker Compose command line (CLI). The task can be used by itself, or as part of a chain of tasks to debug an application within a Docker container.

The most important configuration setting for the docker-compose task is dockerCompose:

• The dockerCompose object specifies parameters for the Docker Compose command. Values specified by this object are applied directly to Docker Compose CLI invocation.

See property reference for full list of all task properties.

Example configuration

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run docker-compose up",
      "type": "docker-compose",
      "dockerCompose": {
        "up": {
          "detached": true,
          "build": true,
          "services": ["myservice"]
        },
        "files": [
          "${workspaceFolder}/docker-compose.yml",
          "${workspaceFolder}/docker-compose.debug.yml"
        ]
      }
    }
  ]
}

Compose task reference

Here are all properties available for configuring docker-compose task. All properties are optional unless indicated otherwise.

dockerCompose object properties

up object properties

down object properties

Command customization

The Docker extension executes a number of Docker CLI commands when you perform various operations, such as to build images, run containers, attach to containers, and view container logs. Some of these commands have a large number of optional arguments, often used in very specific scenarios. As an alternative to the above Visual Studio Code tasks, several commands can be customized when tasks are not in use.

For example, the tokens ${serviceList} and ${profileList} in the Compose Up command allows for easily starting a subset of the services within your Docker Compose YAML file(s).

For each of these customizable Docker commands, a configuration setting is available to set the template of what to execute. Alternatively, you can define multiple templates, optionally with a regular expression, which when matched, hints the context in which a template should be used. The templates support some tokens similar to launch.json and tasks.json, for example, ${workspaceFolder}.

Settings JSON schema

You have two options for configuring each of the templates (listed below). The first option is a single template that overrides the default behavior:

{
  "docker.commands.build": "docker build --rm -f \"${dockerfile}\" -t ${tag} \"${context}\""
}

The second option is multiple templates that will be chosen based on the match regular expression, as well as user input.

For example, three templates are shown in the following example:

{
  "docker.commands.build": [
    {
      "label": "Default build command",
      "template": "docker build --rm -f \"${dockerfile}\" -t ${tag} \"${context}\""
    },
    {
      "label": "Alpine-specific build command",
      "template": "docker build -p 1234:1234 -f \"${dockerfile}\" -t ${tag} \"${context}\"",
      "match": "alpine"
    }
  ]
}

Selection behavior

The command template chosen to execute is selected based on the following rules:

1. If no setting is configured, the default command template is chosen.
2. If only a single template is configured (the first example above), that template is chosen.
3. If multiple templates are configured:
   1. Constrained templates are checked. A constrained template has match. The match regular expression is compared against contextual hints--for example, image name, container name, etc.
   2. If multiple constrained templates apply, the user will be prompted to choose. If only one applies, the user will not be prompted.
   3. If there no applicable constrained templates, unconstrained templates are checked. An unconstrained template does not have match, and is therefore always applicable.
   4. If multiple unconstrained templates apply, the user will be prompted to choose. If only one applies, the user will not be prompted.

Docker Build

Supported tokens:

Note: If the docker.commands.build setting does not contain the ${tag} token, the user will not be prompted to enter/confirm a tag.

Note: The match regular expression will be compared against the selected Dockerfile name and the workspace folder name.

Docker Run

Supported tokens:

Note: The match regular expression will be compared against the full tag of the selected image.

Docker Attach

Supported tokens:

Note: The match regular expression will be compared against the container name and full tag of the container image.

Docker Logs

Supported tokens:

Note: The match regular expression will be compared against the container name and full tag of the container image.

Docker Compose Up

Supported tokens:

Docker Compose Down

Supported tokens:

Additional supported tokens

In addition to the command-specific supported tokens, the following tokens are supported in all command templates: