Create a development container using Visual Studio Code Remote Development (2023)

ÖContainers for Visual Studio code developmentExtension allows you to use aDocker-Containeras a complete development environment. You can use it to open any folder or repository in a container and use the full functionality of Visual Studio Code. Adevcontainer.jsonFile in your project tells VS Code how to access (or create) adevelopment containerwith a well-defined tool and runtime stack. This container can be used to run an application or separate tools, libraries, or runtimes required to work with a code base.

Path to create a development container

In this document, we will walk through the steps to create a development container (dev) in VS Code:

1. create adevcontainer.json, which describes how VS Code should start the container and what to do after connecting.
2. Make and persist changes to the development container using a Dockerfile, e.g. B. Installing new software.
3. Configure multiple containers via Docker Compose.
4. As you make changes, create your development container to ensure the changes take effect.

After each of the above steps, you will have a fully functional development container and can proceed to the next step in this tutorial to add more functionality or to finish and continue working in the current development environment.

Note: The Dev Containers extension has aDevelopment Container: Add development container configuration files...Command that allows you to select a predefined container configuration from a list. If you prefer to have a full development container out of the box instead of thedevcontainer.jsonand Dockerfile walkthrough you can skipAutomate the creation of development containers.

Create a devcontainer.json file

The configuration of the VS Code container is done in adevcontainer.jsonArchive. This file is similarlaunch.jsonFile for debug configurations but used to start (or attach) your development container. The development container configuration is located at.devcontainer/devcontainer.jsonor as saved.devcontainer.jsonFile (note the dot prefix) in the root of your project.

You can use an image as a starting point for yoursdevcontainer.json. An image is like a minidisk drive with a set of tools and an operating system preinstalled. You can get images from a container registry, which is a collection of repositories that store images. Here's a simple exampledevcontainer.jsonuses the prebuilt TypeScript and Node.js VS Code Development ContainerBild:

{ "Bild":"mcr.microsoft.com/devcontainers/typescript-node:0-18"}

You can change your configuration to do things like:

• Install additional tools like Git in the container.
• Installs extensions automatically.
• Forward or publish additional ports.
• Define runtime arguments.
• reuse orExtend your existing Docker Compose setup.
• add moreAdvanced container setup.

For this example, if you want to install theExtension for code spell checkingin your container and automatically forward port 3000, yourdevcontainer.jsonit would look like this:

{ "Bild":"mcr.microsoft.com/devcontainers/typescript-node", "Adjustments": { "vscode": { "extensions": ["streetsidesoftware.code-spellcheck"]}}, "forwardPorts": [3000]}

Monitoring:Additional configuration is already added to the container based on what is included in the base image. For example, we added thestreetsidesoftware.code-spellcheckExtension above, and the container is also included"dbaeumer.vscode-eslint"Ifthis is partmcr.microsoft.com/devcontainers/typescript-node. This is done automatically during precompilation with devcontainer.json, which you can read more about atStem section.

with abovedevcontainer.json, your development container is functional and you can connect to it and start developing. Try theDev Container: Don't rebuild a containerCommand:

After running this command, when you restart VS Code, you'll find yourself in a Node.js and TypeScript development container with port 3000 forwarded and the ESLint extension installed. Once connected, watch the green remote indicator to the left of the status bar to indicate that you are connected to your development container:

Additional development container scenarios

Through adevcontainer.jsonfile you can:

• Spin a standalone container to isolate your toolchain or speed up setup.
• Working with an application deployed in an image-defined containerDockerfile, orDocker composition.
• Use Docker or Kubernetesfrom a development container to build and deploy your application.

Sedevcontainer.jsonsupported workflows don't meet your needs, you can tooappend to an already running container.

Top:Want to use a remote Docker host? see theDevelop on a remote Docker hostArticle for configuration details.

install additional software

You may want to install additional software in your development container. Once VS Code is connected to the container, you can open a VS Code terminal and run any command on the operating system inside the container. This allows installing new command line utilities and activating databases or application services from within the Linux container.

Most container images are based on Debian or Ubuntu, with thefitorapt-getCommand is used to install new packages. You can learn more about the commandin the Ubuntu documentation. Alpine images include asimilarapkcommandwährend CentOS / RHEL / Oracle SE / Fedora-ImagesuseYummyorrecentlydnf.

The documentation for the software you are trying to install often has specific instructions, but you may not need to prefix commandssudoif you run the container as root.

For example:

# When run as rootapt-get updateapt-get install <pacote>

As long as you run as root, you can install the softwaresudoconfigured in your container. All predefined containers havesudoconfigure, but theAdd a non-root user to a containerThe article can help you configure this for your own containers. Regardless of whether you install and configuresudo, you can use it if you run it as any user, including root.

# If sudo is installed and configuredsudo apt-get updatesudo apt-get install <pacote>

Suppose you want to install Git. You can run the following commands in VS Code's built-in terminal:

# If sudo is installed and configuredsudo apt-get update# Install Gitsudo apt-get install git

You can also use the"Resources"property onedevcontainer.jsonInstall tools and languages ​​from a predefined setresourcesor even your own.

For example, you can install the latest version of Azure CLI as follows:

"Resources": { „ghcr.io/devcontainers/features/azure-cli:1“: { "Execution":"Latest"}}

see theFunctional specification of the development containerfor more details.

Rebuild

When editing the content of.devcontainerYou must recreate folders for the changes to take effect. Use theDevelopment container: Rebuild containerCommand for your container to update.

However, if yourebuildthe container, you mustreinstallanything you installed manually. To avoid this problem, you can use thepostCreateCommandproperty onedevcontainer.json.

ÖpostCreateCommandThe actions are run as soon as the container is created, so you can also use the property to run commands likeinstall npmor to run a shell script in your source tree (if you have it mounted).

"postCreateCommand":"bash scripts/install-dev-tools.sh"

You can also use an interactive bash shell for your.bashrcis selected and your shell will automatically adapt to your environment:

"postCreateCommand":"bash -i scripts/install-dev-tools.sh"

Tools like NVM will not work without use-EUTo put the shell in interactive mode:

"postCreateCommand":"bash -i -c 'nvm install --lts'"

The command must end or the container will not start. For example, when you add an app, start topostCreateCommand, the command was not completed.

There's one toopostStartCommandwhich runs every time the container is started. Parameters behave the same waypostCreateCommand, but the commands are run at startup instead of build.

Instead of linking directly to an imagedevcontainer.jsonor software installation by thepostCreateCommandorpostStartCommand, an even more efficient approach is to use a Dockerfile.

Dockerfile

A Dockerfile will also live in the.devcontainerfolder. You can replace thoseBildproperty onedevcontainer.jsoncomdockerfile:

{ "To build": {"dockerfile":"Dockerfile"}, "Adjustments": { "vscode": { "extensions": ["dbaeumer.vscode-eslint"]}}, "forwardPorts": [3000]}

If you make changes, e.g. For example, when installing new software, the changes made to the Dockerfile persist even after the development container is rebuilt.

Use in your DockerfileVONto denote the picture, and theKORREInstructions for installing software. You can use&&to chain multiple commands together.

VONmcr.microsoft.com/devcontainers/javascript-node:0-18KORREapt-get update && export DEBIAN_FRONTEND=noninteractive \&& apt-get -y install git

Note orDEBIAN_FRONTENDexport avoids warnings when you switch to working with your container.

Automate the creation of development containers

Instead of creating one.devcontainermanually by selectingDevelopment Container: Add development container configuration files...command from the command palette (F1) adds the necessary files to your project as a starting point, which you can further customize to suit your needs.

The command allows you to select a predefined container configuration from a list based on the contents of your folder:

The predefined container settings you can choose from are taken from ourOwn and community index, which is part ofSpecification of the development container. We host a number of templates as part of the specificationdevcontainers/templates-Repository. You can browse theOriginFolders of this repository to view the content of each model.

At the end of useDevelopment Container: Add development container configuration files..., see the list of available resources, which are tools and languages ​​that you can easily place in your development container.Development Container: Configure container resourcesallows you to update an existing configuration.

You can also reuse an existing Dockerfile:

Now that you have onedevcontainer.jsonand Dockerfile, we look at the general process for editing container configuration files.

Full configuration edit loop

Editing the container configuration is easy. Because rebuilding a container "resets" the container to its original content (except for its local source code), VS Code is not automatically rebuilt when you edit a container configuration file (devcontainer.json,Dockerfile, zdocker-compose.yml). Instead, there are several commands that can be used to make editing your configuration easier.

Here is the typical editing loop with these commands:

1. Start withDevelopment Container: Add development container configuration files...in the command palette (F1).
2. Edit the content of.devcontainerinsert as needed.
3. try it withDev Container: Don't rebuild a container.
4. If you see an error, selectOpen folder locallyin the dialog box that appears.
5. After the window reloads, a copy of theconstruction logis displayed in the console to help you investigate the problem. Edit the content of.devcontainerinsert as needed. (You can also use theDevelopment Container: Show container logcommand to show the log again when you close it.)
6. reapDevelopment Container: Rebuild and reopen in the containerand continue to step 4 if necessary.

If you already have a successful build, you can still edit the contents of the file.devcontainerFolder as needed when connected to the container, and then selectDevelopment container: Rebuild containerin the command palette (F1) for the changes to take effect.

You can also iterate your container withDev-Container: clone repository on container volumeCommand.

1. Start withDev-Container: clone repository on container volumein the command palette (F1). If the repository you entered doesn't have adevcontainer.jsonThis will prompt you to choose a starting point.
2. Edit the content of.devcontainerinsert as needed.
3. try it withDEv-Container: Rebuild container.
4. If you see an error, selectOpen into recovery containerin the dialog box that appears.
5. Edit the content of.devcontainerFolders as needed in this "recovery container".
6. UseDev Container: Don't rebuild a containerand continue to step 4 if you continue to have problems.

Using Docker Compose

In some cases, a single container environment is not enough. Suppose you want to add another complex component to your setup, e.g. B. a database. You can try adding it directly to Dockerfile or via an additional container. Luckily Dev supports ContainersDocker compositionmanaged configurations with multiple containers.

You can also:

1. Working with a service defined in an existing, unmodified servicedocker-compose.yml.
2. create a new onedocker-compose.yml(or make a copy of an existing one) that you use to develop a service.
3. Extend your existing Docker Compose configurationto develop the service.
4. To do this, use separate VS Code windowsWork with multiple services defined by Docker Composeat once.

Monitoring:Some extensions may not work when using Alpine Linux containersglibcnative code dependencies within the extension.

VS Code can be configured this wayautomatically start all necessary containersfor a specific service in a Docker Compose file. If you have already started the configured containers from the command line, VS Code will do soappend to the running serviceYou indicated instead. This gives your multi-container workflow the same quick setup benefits described above for the Docker Image and Dockerfile workflows, while still allowing you to use the command line if you prefer.

To get started quicklyopen to pasteYou want to work in VS Code and theDevelopment Container: Add development container configuration files...command in the command palette (F1).

You will be prompted to select a predefined container configuration in ourOwn and community indexin a filterable list sorted by the contents of your folder. In the VS Code UI, you can choose one of the following templates as a starting point for Docker Compose:

• Docker Compose is present- Contains a set of files that you can put into an existing project reusing onedocker-compose.ymlFile in the root of your project.
• Node.js and MongoDB- A Node.js container that connects to a MongoDB database in another container.
• Python und PostgreSQL- A Python container that connects to PostgreSQL in another container.
• Docker-de-Docker Compose- Includes the Docker CLI and demonstrates how you can use it to access your local Docker installation from within a per-volume development container by mounting the Docker Unix socket.

Once you've made your selection, VS Code will add it.devcontainer/devcontainer.json(or.devcontainer.json) for the folder.

You can also create your configuration manually. To reuse an unmodified Docker Compose file, you can use thedockerComposeFileeServiceproperties inside.devcontainer/devcontainer.json.

For example:

{ "Name":"[Optional] Your project name here", "dockerComposeArquivo":"../docker-compose.yml", "Service":"the-name-of-the-service-you-want-to-work-with-vscode", "Pasta Workspace":"/default/workspace/path/in/container/to/open", "shutdown action":"stopCompor"}

see thedevcontainer.json referencefor information about other available properties, such asWorkspacePastaeShutdownAktion.

After adding a.devcontainer/devcontainer.jsonfile in your folder, run theDev Container: Don't rebuild a containercommand (orDevelopment container: Open folder in container...if you are not already in a container) from the command palette (F1).

If the containers aren't already running, VS calls Codedocker-compose -f ../docker-compose.yml hochin this example. theServiceThe property specifies which service in your Docker Compose file you want VS Code to connect to, not which service to start with. If you started them manually, VS Code will attach to the service you specified.

You can also create a development copy of your Docker Compose file. For example if you had.devcontainer/docker-compose.devcontainer.yml, you would simply change the following line todevcontainer.json:

"dockerComposeArquivo":"docker-compose.devcontainer.yml"

However, a better approach is usually to avoid making a copy of the Docker Compose file.expand with another. we will coverExpand a Docker Compose filein the next section.

To prevent the container from shutting down when the default container command fails or exits, you can modify your Docker Compose file for the specified servicedevcontainer.jsonas follows:

# Overrides the default command so things don't exit after the process exits.command:/bin/sh -c "while sleeping 1000; do :; done"

If you haven't already, you can"bind" mount your local source codeinside the container with theList of volumes in your Docker Compose file.

For example:

volumes: # Mount the project folder on '/workspace'. The target path within the container # must match your application's expectations. In this case, the compose file # in a subfolder, so mount '..'. You would then reference that path as # "workspaceFolder" in ".devcontainer/devcontainer.json" so VS Code starts here.-..:/workspace:cached

However, on Linux it may be necessary to configure andSpecify a non-root userIf you use a mandatory mount or a file you create, you are root. SeeAdding a non-root user to your development containerfor details. To have VS Code run as a different user, add thisdevcontainer.json:

"remoteUser":"your-username-here"

If you want all processes to run under a different user, add this to the appropriate service in your Docker Composefile:

from the user:your-username-here

If you are not creating a custom Dockerfile for development, you may want additional developer tools such ascurlingin the service container. Although less efficient than adding these tools to the container image, you can also use thepostCreateCommandproperty for this purpose.

Verinstall additional softwarefor more information about installing the software anddevcontainer.json referencefor more information aboutpostCreateCommandProperty.

If your app was built with C++, Go, or Rust, or any other language that uses a ptrace-based debugger, you must also add the following settings to your Docker Compose file:

# Required for ptrace-based debuggers like C++, Go, and Rustcap_add:-SYS_PTRACEsecurity opt:-seccomp: unlimited

After creating your container for the first time, you need to run theDevelopment container: Rebuild containerCommand for updates toodevcontainer.json, your Docker Compose files or related Dockerfiles take effect.

Using localhost in Docker Compose

You can add more services to yourdocker-compose.ymlfile as described inDocker Documentation. However, if you want everything running on this service to be available in the container on localhost or you want to route the service locally, add this line to the service's configuration:

# Run the service on the same network as the database container, enable "forwardPorts" in the devcontainer.json function.network mode:Service: DB

You can see an exampleNetwork mode: Service: dbnoNode.js and MongoDB sample development containers.

Extend your Docker Compose file for development

Pointing to an existing/non-development deploymentdocker-compose.ymlit has some potential downsides.

For example:

• Docker Compose shuts down a container when its entry point shuts down. This is problematic for situations where you need to debug and repeatedly restart your application.
• You might also not map the local file system to the container or not free ports for other resources like databases that you want to access.
• You may want to copy the content of your location.sshfolder in the container or set the ptrace options described above inUsing Docker Compose.

You can solve these and similar problems by extending your entire Docker Compose configuration withseveraldocker-compose.ymlfilesthat replace or supplement your client.

For example, consider this add-on.devcontainer/docker-compose.extend.ymlArchive:

execution:'3'Services: Your-service-name-here: volumes: # Mount the project folder on '/workspace'. While this file resides in .devcontainer, # Mounts are relative to the first file in the list one level up.-.:/workspace:cached # [Optional] Required for ptrace-based debuggers such as C++, Go, and Rust cap_add:-SYS_PTRACE security opt:-seccomp: unlimited # Overrides the default command so things don't exit after the process exits. command:/bin/sh -c "while sleeping 1000; do :; done"

The same file can provide additional settings such as port mappings if needed. To use it, refer to your originaldocker-compose.ymlfile plus.devcontainer/docker-compose.extend.ymlin a specific order:

{ "Name":"[Optional] Your project name here", // File order is important as later files overwrite earlier ones "dockerComposeArquivo": ["../docker-compose.yml","docker-compose.extend.yml"], "Service":"your-service-name-here", "Pasta Workspace":"/Workplace", "shutdown action":"stopCompor"}

VS Code will thenautomatically use both fileswhen starting any container. You can also start them from the command line like this:

docker-compose -f docker-compose.yml -f .devcontainer/docker-compose.extend.yml hoch

DuringpostCreateCommandproperty you can install additional tools in your container, in some cases you might want to have a specific Dockerfile for development. You can also use the same approach to reference aDockerfilespecifically for development without modifying your existing Docker Compose file. For example, you can update.devcontainer/devcontainer.extend.ymlas follows:

execution:'3'Services: Your-service-name-here: # Note that the Dockerfile path and context are relative to *main* # docker-compose.yml file (first in devcontainer.json "dockerComposeFile" # Diversity). The following example assumes that your main file is in the root of your project. To build: context:. dockerfile:.devcontainer/Dockerfile volumes:-.:/workspace:cached command:/bin/sh -c "while sleeping 1000; do :; done"

congratulations! You have now set up a development container in Visual Studio Code. Read on to learn how to share container configurations between teammates and multiple projects.

Add configuration files to a repository

You can easily share a custom development container template for your project by adding itdevcontainer.jsonSource Control Files. By including these files in your repository, anyone who opens a local copy of your repository in VS Code will be automatically prompted to reopen the folder in a container, provided they have the Dev Containers extension installed.

In addition to the benefits of your team using a consistent environment and toolchain, it also makes it easier for new contributors or team members to get started quickly. New contributors require less guidance and have fewer issues related to setting up the environment.

Add an open seal in the development container

You can also add a badge or link to your repository so users can easily open your project in Dev Containers. It installs the Dev Containers extension and clones the repository into a container if neededVolumeand start the dev container.

As an example, a badge to openhttps://github.com/microsoft/vscode-remote-try-javait would look like this:

[![Open in dev containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/vscode-remote-try-java)

You can also add oneopen in the development containerdirect connection:

If you already have VS Code and Docker installed, click the badge above or [on here](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/vscode-remote-try-java) begin. When you click these links, VS Code will automatically install the Dev Containers extension if needed, clone the source code to a container volume, and launch a development container for use.

Alternative: Repository-Konfigurationsordner

In some cases, you might want to create a configuration for a repository that you don't control, or you might want no configuration included in the repository itself. To deal with this situation, you can configure a location on your local file system to store configuration files that are automatically selected based on the repository.

First update theDev > Container: Repository-Konfigurationspfade user configurationwith the local folder you want to use to store your repository container configuration files.

In the config editor you can search for "dev container repo" to find the config:

Next place yours.devcontainer/devcontainer.json(and associated files) in a subfolder reflecting the remote location of the repository. For example, if you want to create a configuration forgithub.com/devcontainers/templates, you would create the following folder structure:

📁 github.com 📁 devcontainers 📁 modelos 📁 .devcontainer

Once the configuration is in place, it will be automatically selected when you use any of the Dev Containers commands. Once inside the container, you can also chooseDevelopment Container: Open the container configuration filefrom the command palette (F1) to open the related onedevcontainer.jsonfile and make further edits.

The path used to find the configuration is derived from the output ofgit remote -v. If the configuration is not found when you try to reopen the folder in a container, check the logDevelopment Container: Show container login the command palette (F1) for the list of checked paths.

Next Steps

• Attach to a running container- Attach to an already running Docker container.
• Advanced Containers- Find solutions for advanced container scenarios.
• devcontainer.json reference- Check thedevcontainer.jsonthe plan.

12.07.2022