Tutorial: Getting Started with Dev Containers

Prerequisites

Before you start, ensure you have a Docker plugin installed and set up.

Step 1. Prepare a project

Since the devcontainer.json is a necessary configuration file for building Dev Containers, it should be present in the project. The file is placed in the .devcontainer folder in the project root; there could be some other folder in between, like .devcontainer/.../.../devcontainer.json.

There are two options to quickly start creating Dev Containers: create a simple file or use an in-IDE feature to create a configuration file from the template.

The minimal requirement for a Dev Container is the image from which it would be built.

In the project view, right-click the project name and select, New | File.
Add the file name (devcontainer.json).
Open the file in the editor and add the following code:
{ image: "ubuntu:latest" }

In the project view, right-click the project name and select, New | Dev Container Config.
In the dialog that opens, WebStorm displays a default container configuration. The default template is enough to create a Dev Container, but any other language-specific template could be selected from the Dev Container Template dropdown if necessary.
Click OK to create a relatively simple (but full of comments) devcontainer.json:
// Default Ubuntu-based DevContainer Template. // For more customization options, see https://containers.dev/implementors/json_reference { name: "Default", image: "ubuntu:latest", customizations : { // Configure JetBrains IDE-specific properties jetbrains : { backend : "IntelliJ", settings : { // IDE settings can be added via “Show context actions”|“Add currently modified settings from IDE”. // A complete list of supported settings is also available through auto-completion }, plugins: [ // A set of plugin IDs. // Plugin ID can be found on the corresponding plugin’s page at https://plugins.jetbrains.com. ] } }, features: { "ghcr.io/devcontainers/features/git" : {}, // Add additional features to your project using auto-completion. }, // Comment out to connect as the root user. remoteUser: "ubuntu" }

Step 2. Prepare for a build process

You need to consider several additional details to successfully build a container.

Which Dev Container implementation will be used. For the Remote Development (aka first or old) implementation, ensure that the Open devcontainer projects natively option in Settings | Advanced Settings is disabled; for the native mode (aka second) implementation, enable this option.

When RD implementation is used, it is advised to set up the IDE to provide an extended backend choice: How to select the specific IDE backend version for dev containers.

To use the custom remote development backend (maybe necessary to check problems in not-published IDE builds), see IDE backend is not downloaded correctly when building dev containers.

Step 3. Start a Dev Container build

The easiest option to start a Dev Container build is to do it from the opened devcontainer.json file through the gutter icon:
After the build starts, the Services view should be opened automatically to display the build process:
Depending on the implementation chosen (Remote Development vs native mode), the following flow differs a bit.
Select the backend version from the list and wait while it and the Client are downloaded:
In some cases, if the Dev Container build and backend deployment process takes more than 10 seconds, the Client will not be opened; instead, the notification with the Connect button will be shown in the IDE. Press the button.
Press the Trust Project button in the following window, and wait while Client opens:
How to understand if it is already a project in the Dev Container opened? By the Backend Status Details widget on the top left.
Since there is no backend deployment step, the Dev Container project will be opened in the IDE instantly. If the Open project in option in Settings | Appearance & Behavior | System Settings is set up to Ask, the project will be opened after confirmation.
To understand if the project is opened in a Dev Container that uses a native mode, check the unusual project root path and a widget that displays the Dev Container information on the top left of your editor.