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 Core), 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 thedocker-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:
Property | Inferred Value |
---|---|
dockerBuild.context | The same directory in which the package.json resides. |
dockerBuild.dockerfile | The file Dockerfile in the same directory as the package.json resides. |
dockerBuild.tag | The application’s name property in package.json (if defined), else the base name of the folder in which package.json resides. |
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:
Property | Inferred Value |
---|---|
dockerBuild.context | The default context is the workspace folder. |
dockerBuild.dockerfile | The default Dockerfile path will be in the root of the workspace folder. |
dockerBuild.tag | The base name of the root workspace folder. |
dockerBuild.pull | Defaults to true in order to pull new base images before building. |
.NET Core (docker-build)
Minimal configuration using defaults
When you build a .NET Core-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 Core-based images, the docker-build
task infers the following options:
Property | Inferred Value |
---|---|
dockerBuild.context | The root workspace folder. |
dockerBuild.dockerfile | The file Dockerfile in the root workspace folder. |
dockerBuild.tag | The base name of the root workspace folder. |
Build task reference
Here are all properties available for configuring docker-build
task. All properties are optional unless indicated otherwise.
Property | Description |
---|---|
dockerBuild | Options for controlling the docker build command executed (see below).Required unless platform is set. |
platform | Determines the platform: .NET Core (netcore ) or Node.js (node ) and default settings for docker build command. |
node | Determines options specific for Node.js projects (see below). |
python | There are no object properties for Python in the docker-build task. |
netCore | Determines options specific for .NET Core projects (see below). |
dockerBuild object properties
Property | Description | docker build CLI Equivalent |
---|---|---|
context | The path to the Docker build context. Required, unless inferred from the platform. | PATH |
dockerfile | The path to the Dockerfile. Required, unless inferred from the platform. | -f or —file |
tag | The tag applied to the Docker image. Required, unless inferred from the platform. | -t or —tag |
buildArgs | Build arguments applied to the command line. This is a list of key-value pairs. | —build-arg |
labels | Labels added to the Docker image. This is a list of key-value pairs (a JSON object). In addition to labels specified here, a label com.microsoft.created-by , set to visual-studio-code is added to the image. This behavior can be turned off by setting includeDefaults property of the labels object to false. | —label |
target | The target in the Dockerfile to build to. | —target |
pull | Whether or not to pull new base images before building. | —pull |
node object properties (docker-build task)
Property | Description | Default |
---|---|---|
package | The path to the package.json file associated with the Dockerfile and docker-build task. | The file package.json in the root workspace folder. |
netCore object properties (docker-build task)
Property | Description |
---|---|
appProject | The .NET Core project file (.csproj , .fsproj , etc.) associated with the Dockerfile and docker-build task.Required always. |
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 thedocker-run
task determines Docker run defaults.
See property reference for full list of all task properties.
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 Core.
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:
Property | Inferred Value |
---|---|
dockerRun.command | Generated from the npm start script in the package.json (if it exists), else generated from the main property in the package.json . |
dockerRun.containerName | Derived from the application package name. |
dockerRun.image | The tag from a dependent docker-build task (if one exists) or derived from the application package name, itself derived from the name property within package.json or the base name of the folder in which it resides. |
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:
Property | Inferred Value |
---|---|
dockerRun.command | Generated by the Python object and is called by the Python Debugger. |
dockerRun.containerName | Derived from the base name of the root workspace folder. |
dockerRun.image | The tag from a dependent docker-build task (if one exists) or derived from the base name of the root workspace folder. |
.NET Core (docker-run)
Minimal configuration using defaults
When building a .NET Core-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 Core-based images, the docker-run
task infers the following options:
Property | Inferred Value |
---|---|
dockerRun.containerName | Derived from the base name of the root workspace folder. |
dockerRun.env | Adds the following environment variables as required: ASPNETCORE_ENVIRONMENT , ASPNETCORE_URLS , and DOTNET_USE_POLLING_FILE_WATCHER . |
dockerRun.image | The tag from a dependent docker-build task (if one exists) or derived from the base name of the root workspace folder. |
dockerRun.os | Linux |
dockerRun.volumes | Adds the following volumes as required: the local application folder, the source folder, the debugger folder, the NuGet package folder, and NuGet fallback folder. |
Run task reference
Here are all properties available for configuring docker-run
task. All properties are optional unless indicated otherwise.
Property | Description |
---|---|
dockerRun | Options for controlling the docker run command executed (see below).Required unless platform is set. |
platform | Determines the platform: .NET Core (netcore ) or Node.js (node ) and default settings for docker run command. |
node | For Node.js projects, this controls various options (see below). |
python | For Python projects, this controls various options (see below). |
netCore | For .NET Core projects, this controls various options (see below). |
dockerRun object properties
Property | Description | CLI Equivalent |
---|---|---|
image | The name (tag) of the image to run. Required unless inferred from the platform. | IMAGE |
command | The command to run upon starting the container. Required, unless inferred from the platform. | COMMAND [ARG…] |
containerName | The name given to the started container. Required, unless inferred from the platform. | —name |
env | Environment variables set in the container. This is a list of key-value pairs. | -e or —env |
envFiles | This is a list of .env files. | —env-file |
labels | Labels given to the started container. This is a list of key-value pairs. | —label |
network | The name of the network to which the container will be connected. | —network |
networkAlias | The network-scoped alias for the started container. | —network-alias |
os | Default is Linux , the other option is Windows . The container operating system used. | N/A |
ports | The ports to publish (map) from container to host. This is a list of objects (see below). | -p or —publish |
portsPublishAll | Whether to publish all ports exposed by the Docker image. Defaults to true if no ports are explicitly published. | -P |
extraHosts | The hosts to add to the container for DNS resolution. This is a list of objects (see below). | —add-host |
volumes | The volumes to map into the started container. This is a list of objects (see below). | -v or —volume |
ports object properties
Property | Description | Default |
---|---|---|
containerPort | The port number bound on the container. Required. | |
hostPort | The port number bound on the host. | (randomly selected by Docker) |
protocol | The protocol for the binding (tcp or udp ). | tcp |
extraHosts object properties
Property | Description |
---|---|
hostname | The hostname for DNS resolution. Required. |
ip | The IP address associated with the above hostname. Required. |
volumes object properties
Property | Description | Default |
---|---|---|
localPath | The path on the local machine that will be mapped. Required. | |
containerPath | The path in the container to which the local path will be mapped. Required. | |
permissions | Permissions the container has on the mapped path. Can be ro (read-only) or rw (read-write). | Container dependent. |
node object properties (docker-run task)
Property | Description | Default |
---|---|---|
package | The path to the package.json file associated with the docker-run task. | The file package.json in the root workspace folder. |
enableDebugging | Whether or not to enable debugging within the container. | false |
inspectMode | Defines the initial interaction between the application and the debugger (default or break ).The value default allows the application to run until the debugger attaches.The value break prevents the application from running until the debugger attaches. | default |
inspectPort | The port on which debugging should occur. | 9229 |
python object properties (docker-run task)
Property | Description | Default |
---|---|---|
args | Arguments passed to the Python app. | Platform dependent. Defaults of scaffolding shown above |
debugPort | The port that the debugger will listen on. | 5678 |
wait | Whether to wait for debugger to attach. | true |
module | The Python module to run (only module or file should be chosen). | |
file | The Python file to run (only module or file should be chosen). |
netCore object properties (docker-run task)
Property | Description |
---|---|
appProject | The .NET Core project file (.csproj , .fsproj , etc.) associated with docker-run task.Required. |
configureSsl | Whether to configure ASP.NET Core SSL certificates and other settings to enable SSL on the service in the container. |
enableDebugging | Whether to enable the started container for debugging. This will infer additional volume mappings and other options necessary for debugging. |
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. Many of these commands can be customized.
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 is a single template that overrides the default behavior:
{
"docker.commands.build": "docker build --rm -f \"${dockerfile}\" -t ${tag} \"${context}\""
}
The second is multiple templates that will be chosen based on the match
regular expression as well as user input.
For example, two 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:
- If no setting is configured, the default command template is chosen.
- If only a single template is configured (the first example above), that template is chosen.
- If multiple templates are configured:
- Templates containing a defined
match
property are examined first. Thematch
regular expression is compared against the context—for example, image name, container name, etc. All matching templates are selected. More information on the matching context is available below. - If no templates match the
match
property, all templates without a definedmatch
property are selected. - If no templates match the
match
property, and there are no templates without a definedmatch
property, then the default command template is chosen. - Any time that multiple templates are selected, the user will be prompted to choose between them on which to execute.
- Templates containing a defined
Docker Build
Configuration Setting | Default Value |
---|---|
docker.commands.build | docker build —rm -f “${dockerfile}” -t ${tag} “${context}” |
Supported tokens:
Token | Description |
---|---|
${dockerfile} | The workspace-relative path of the selected Dockerfile . |
${tag} | The value entered/confirmed by the user upon invoking the build command. If previously built, defaults to the previously entered value for that Dockerfile . |
${context} | If set, the value of the docker.imageBuildContextPath configuration setting. Otherwise, the workspace-relative folder in which the Dockerfile resides. |
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
Configuration Setting | Default Value |
---|---|
docker.commands.run | docker run —rm -d ${exposedPorts} ${tag} |
docker.commands.runInteractive | docker run —rm -it ${exposedPorts} ${tag} |
Supported tokens:
Token | Description |
---|---|
${exposedPorts} | Generated from the list of exposed ports in the image (ultimately from the Dockerfile ), where each exposed port is mapped to the same port on the local machine. For example, “EXPOSE 5000 5001” would generate “-p 5000:5000 -p 5001:5001” . |
${tag} | The full tag of the selected image. |
Note: The
match
regular expression will be compared against the full tag of the selected image.
Docker Attach
Configuration Setting | Default Value |
---|---|
docker.commands.attach | docker exec -it ${containerId} ${shellCommand} |
Supported tokens:
Token | Description |
---|---|
${containerId} | The ID of the container to attach to. |
${shellCommand} | The value of the docker.attachShellCommand.linuxContainer or docker.attachShellCommand.windowsContainer configuration setting, as appropriate. |
Note: The
match
regular expression will be compared against the container name and full tag of the container image.
Docker Logs
Configuration Setting | Default Value |
---|---|
docker.commands.logs | docker logs -f ${containerId} |
Supported tokens:
Token | Description |
---|---|
${containerId} | The ID of the container to view the logs for. |
Note: The
match
regular expression will be compared against the container name and full tag of the container image.
Docker Compose Up
Configuration Setting | Default Value |
---|---|
docker.commands.composeUp | docker-compose ${configurationFile} up ${detached} ${build} |
Supported tokens:
Token | Description |
---|---|
${configurationFile} | Set to -f plus the workspace-relative path to the selected Docker Compose YAML file. |
${detached} | Set to -d if the configuration setting docker.dockerComposeDetached is set to true . Otherwise, set to “” . |
${build} | Set to —build if the configuration setting docker.dockerComposeBuild is set to true . Otherwise, set to “” . |
Docker Compose Down
Configuration Setting | Default Value |
---|---|
docker.commands.composeDown | docker-compose ${configurationFile} down |
Supported tokens:
Token | Description |
---|---|
${configurationFile} | Set to -f plus the workspace-relative path to the selected Docker Compose YAML file. |
Additional supported tokens
In addition to the command-specific supported tokens, the following tokens are supported in all command templates:
Token | Description |
---|---|
${workspaceFolder} | The selected workspace folder path. |
${config:some.setting.identifier} | The value of any configuration setting, as long as it is a string, number, or boolean. These setting identifiers can be arbitrarily defined and do not need to belong to Visual Studio Code or to any extension. |