Use Docker Compose

Docker Compose provides a way to orchestrate multiple containers that work together. Examples include a service that processes requests and a front-end web site, or a service that uses a supporting function such as a Redis cache. If you are using the microservices model for your app development, you can use Docker Compose to factor the app code into several independently running services that communicate using web requests. This article helps you enable Docker Compose for your apps, whether they are Node.js, Python, or .NET, and also helps you configure debugging in Visual Studio Code for these scenarios.

Also, for single-container scenarios, using Docker Compose provides tool-independent configuration in a way that a single Dockerfile does not. Configuration settings such as volume mounts for the container, port mappings, and environment variables can be declared in the docker-compose YML files.

To use Docker Compose in VS Code using the Container Tools extension, you should already be familiar with the basics ofDocker Compose.

Adding Docker Compose support to your project

If you already have one or more Dockerfiles, you can add Docker Compose files by opening theCommand Palette (⇧⌘P (Windows, LinuxCtrl+Shift+P)), and using theContainers: Add Docker Compose Files to Workspace command. Follow the prompts.

You can add Docker Compose files to your workspace at the same time you add a Dockerfile by opening theCommand Palette (⇧⌘P (Windows, LinuxCtrl+Shift+P)) and using theContainers: Add Docker Files to Workspace command. You'll be asked if you want to add Docker Compose files. If you want to keep your existing Dockerfile, chooseNo when prompted to overwrite the Dockerfile.

The Container Tools extension adds thedocker-compose.yml file to your workspace. This file contains the configuration to bring up the containers as expected in production. In some cases, adocker-compose.debug.yml is also generated. This file provides a simplified mode for starting that enables the debugger.

The VS Code Container Tools extension generates files that work out of the box, but you can also customize them to optimize for your scenario. You can then use theContainers: Compose Up command (right-click on thedocker-compose.yml file, or find the command in theCommand Palette) to get everything started at once. You can also use thedocker-compose up command from the command prompt or terminal window in VS Code to start the containers. Refer to theDocker Compose documentation about how to configure the Docker Compose behavior and what command-line options are available.

With the docker-compose files, you can now specify port mappings in the docker-compose files, rather than in the .json configuration files. For examples, see theDocker Compose documentation.

Tip: When using Docker Compose, don't specify a host port. Instead, let the Docker pick a random available port to automatically avoid port conflict issues.

Add new containers to your projects

If you want to add another app or service, you can runContainers: Add Docker Compose Files to Workspace again, and choose to overwrite the existing docker-compose files, but you'll lose any customization in those files. If you want to preserve changes to the compose files, you can manually modify thedocker-compose.yml file to add the new service. Typically, you can copy the existing service section, paste it to create a new entry, and change the names as appropriate for the new service.

You can run theContainers: Add Docker Files to Workspace command again to generate theDockerfile for a new app. While each app or service has its own Dockerfile, there's typically onedocker-compose.yml and onedocker-compose.debug.yml file per workspace.

In Python projects, you have theDockerfile,.dockerignore,docker-compose*.yml files all in the root folder of the workspace. When you add another app or service, move the Dockerfile into the app's folder.

In Node.js projects, theDockerfile and.dockerignore files will be next to thepackage.json for that service.

For .NET, the folder structure is already set up to handle multiple projects when you create the Docker Compose files,.dockerignore anddocker-compose*.yml are placed in the workspace root (for example, if the project is insrc/project1, then the files are insrc), so when you add another service, you create another project in a folder, sayproject2, and recreate or modify the docker-compose files as described previously.

Debug

First, refer to the debugging documentation for your target platform, to understand the basics on debugging in containers with VS Code:

• Node.js debugging
• Python Container debugging
• .NET debugging

If you want to debug in Docker Compose, run the commandContainers: Compose Up using one of the two Docker Compose files as described in the previous section, and then attach using the appropriateAttach launch configuration. Launching directly using the normal launch configuration does not use Docker Compose.

Create anAttachlaunch configuration. This is a section inlaunch.json. The process is mostly manual, but in some cases, the Container Tools extension can help by adding a pre-configured launch configuration that you can use as a template and customize. The process for each platform (Node.js, Python, and .NET) is described in the following sections.

Node.js

1. On theDebug tab, choose theConfiguration dropdown, chooseNew Configuration and select theContainers: Attach configuration templateContainers: Attach to Node.

2. Configure the debugging port indocker-compose.debug.yml. This is set when you create the file, so you might not need to change it. In the example below, port 9229 is used for debugging on both the host and the container.

    version:'3.4' services:   node-hello:     image:node-hello     build:.     environment:       NODE_ENV:development     ports:       -3000       -9229:9229     command:node --inspect=0.0.0.0:9229 ./bin/www

3. If you have multiple apps, you need to change the port for some of them, so that each app has a unique port. You can point to the right debugging port in thelaunch.json, and save the file. If you omit this, the port will be chosen automatically.

   Here's an example that shows the Node.js launch configuration - Attach:

    "configurations": [     {         "type":"node",         "request":"attach",         "name":"Containers: Attach to Node",         "remoteRoot":"/usr/src/app",         "port":9229 // Optional; otherwise inferred from the docker-compose.debug.yml.     },     // ... ]

4. When done editing theAttach configuration, savelaunch.json, and select your new launch configuration as the active configuration. In theDebug tab, find the new configuration in theConfiguration dropdown.

   

5. Right-click on thedocker-compose.debug.yml file and chooseCompose Up.

6. When you attach to a service that exposes an HTTP endpoint that returns HTML, the web browser doesn't open automatically. To open the app in the browser, choose the container in the sidebar, right-click and chooseOpen in Browser. If multiple ports are configured, you'll be asked to choose the port.

7. Launch the debugger in the usual way. From theDebug tab, choose the green arrow (Start button) or useF5.

Python

For debugging Python with Docker Compose, follow these steps:

1. On theDebug tab, choose theConfiguration dropdown, chooseNew Configuration, choosePython Debugger, and select theRemote Attach configuration template.

   

2. You're prompted to choose the host machine (for example, localhost) and port you want to use for debugging. The default debugging port for Python is 5678. If you have multiple apps, you need to change the port for one of them, so that each app has a unique port. You can point to the right debugging port in thelaunch.json, and save the file. If you omit this, the port will be chosen automatically.

        "configurations": [     {        "name":"Python Debugger: Remote Attach",        "type":"debugpy",        "request":"attach",        "port":5678,        "host":"localhost",        "pathMappings": [            {                "localRoot":"${workspaceFolder}",                "remoteRoot":"/app"            }        ]    }

3. When done editing theAttach configuration, save thelaunch.json. Navigate to theDebug tab, and selectPython Debugger: Remote Attach as the active configuration.

4. If you already have a valid Dockerfile, we recommend running the commandContainers: Add Docker Compose Files to Workspace. This will create adocker-compose.yml file and also adocker-compose.debug.yml, which volume maps and starts the Python debugger in the container. If you do not have a Dockerfile already, we recommend runningContainers: Add Docker Files to Workspace and selectingYes to include Docker Compose files.

   Note: By default, when usingContainers: Add Docker Files to Workspace, choosing the Django and Flask options will scaffold a Dockerfile configured for Gunicorn. Follow the instructions in thePython in a container quickstart to ensure it is configured properly before proceeding.

5. Right-click on thedocker-compose.debug.yml file (example shown below) and chooseCompose Up.

   version:'3.4'services:  pythonsamplevscodedjangotutorial:    image:pythonsamplevscodedjangotutorial    build:      context:.      dockerfile:./Dockerfile    command: ["sh","-c","pip install debugpy -t /tmp && python /tmp/debugpy --wait-for-client --listen 0.0.0.0:5678 manage.py runserver 0.0.0.0:8000 --nothreading --noreload"]    ports:      -8000:8000      -5678:5678

6. Once your container is built and running, attach the debugger by hittingF5 with thePython Debugger: Remote Attach launch configuration selected.

   

   Note: If you would like to import the Python debugger into a specific file, more information can be found in thedebugpy README.

7. When you attach to a service that exposes an HTTP endpoint and returns HTML, the web browser may not open automatically. To open the app in the browser, right-click the container in the Container Explorer and chooseOpen in Browser. If multiple ports are configured, you'll be asked to choose the port.

   

   You're now debugging your running app in the container.

.NET

1. On theDebug tab, choose theConfiguration dropdown, chooseNew Configuration and select theContainer Attach configuration templateContainers: .NET Attach (Preview).

2. VS Code tries to copyvsdbg from the host machine to the target container using a default path. You can also provide a path to an existing instance ofvsdbg in theAttach configuration.

    "netCore": {     "debuggerPath":"/remote_debugger/vsdbg" }

3. When done editing theAttach configuration, savelaunch.json, and select your new launch configuration as the active configuration. In theDebug tab, find the new configuration in theConfiguration dropdown.

4. Right-click on thedocker-compose.debug.yml file and chooseCompose Up.

5. When you attach to a service that exposes an HTTP endpoint that returns HTML, the web browser doesn't open automatically. To open the app in the browser, choose the container in the sidebar, right-click and chooseOpen in Browser. If multiple ports are configured, you'll be asked to choose the port.

6. Launch the debugger in the usual way. From theDebug tab, choose the green arrow (Start button) or useF5.

   

7. If you try to attach to a .NET app running in a container, you'll see a prompt ask to select your app's container.

   

   To skip this step, specify the container name in theAttach configuration in launch.json:

       "containerName":"Your ContainerName"

   Next, you're asked if you want to copy the debugger (vsdbg) into the container. ChooseYes.

   

If everything is configured correctly, the debugger should be attached to your .NET app.

Volume mounts

By default, the Container Tools extension does not do any volume mounting for debugging components. There's no need for it in .NET or Node.js, since the required components are built into the runtime. If your app requires volume mounts, specify them by using thevolumes tag in thedocker-compose*.yml files.

volumes:    -/host-folder-path:/container-folder-path

Docker Compose with multiple Compose files

Workspaces can have multiple docker-compose files to handle different environments like development, test, and production. The content of the configuration can be split into multiple files. For example, a base compose file that defines the common information for all environments and separate override files that define environment-specific information. When these files are passed as input to thedocker-compose command, it combines these files into a single configuration. By default, theContainers: Compose Up command passes a single file as input to the compose command, but you can customize thecompose up command to pass in multiple files usingcommand customization. Or, you can use acustom task to invoke thedocker-compose command with the desired parameters.

Note: If your workspace hasdocker-compose.yml anddocker-compose.override.yml and no other compose files, then thedocker-compose command is invoked with no input files and it implicitly uses these files. In this case, no customization is needed.

Command customization

Command customization provides various ways to customize thecompose up command based on your requirements. The following are few sample command customization for thecompose up command.

Base file and an override file

Let's assume your workspace has a base compose file (docker-compose.yml) and an override file for each environment (docker-compose.dev.yml,docker-compose.test.yml anddocker-compose.prod.yml) and you always rundocker compose up with the base file and an override file. In this case, thecompose up command can be customized as in the following example. When thecompose up command is invoked, the${configurationFile} is replaced by the selected file.

"docker.commands.composeUp": [    {        "label":"override",        "template":"docker-compose -f docker-compose.yml ${configurationFile}  up -d --build",    }]

Template matching

Let's assume you have a different set of input files for each environment. You could define multiple templates with regular expression match, and the selected file name will be matched against thismatch property and the corresponding template will be used.

"containers.commands.composeUp": [    {        "label":"dev-match",        "template":"docker-compose -f docker-compose.yml -f docker-compose.debug.yml -f docker-compose.dev.yml up -d --build",        "match":"dev"    },    {        "label":"test-match",        "template":"docker-compose -f docker-compose.yml -f docker-compose.debug.yml -f docker-compose.test.yml up -d --build",        "match":"test"    },    {        "label":"prod-match",        "template":"docker-compose -f docker-compose.yml -f docker-compose.release.yml -f docker-compose.prod.yml up -d --build",        "match":"prod"    }]

Pick a template when the command is invoked

If you omit thematch property from command templates, you're asked which template to use each timecompose up command is invoked. For example:

"containers.commands.composeUp": [    {        "label":"dev",        "template":"docker-compose -f docker-compose.yml -f docker-compose.common.dev.yml ${configurationFile} up -d --build"    },    {        "label":"test",        "template":"docker-compose -f docker-compose.yml -f docker-compose.common.test.yml ${configurationFile} up -d --build"    },    {        "label":"prod",        "template":"docker-compose -f docker-compose.yml -f docker-compose.common.prod.yml ${configurationFile} up -d --build"    },],

Custom tasks

Rather than use command customization, you can also define a task like the following to invoke adocker-compose command. Please refercustom task for more detail on this option.

{  "type":"shell",  "label":"compose-up-dev",  "command":"docker-compose -f docker-compose.yml -f docker-compose.Common.yml -f docker-compose.dev.yml up -d --build",  "presentation": {    "reveal":"always",    "panel":"new"  }}

Next steps

• Overview of Docker Compose in the Docker documentation
• Troubleshooting