Docker

Preparing to use Docker

1. Download, install and start Docker

To download Docker and find out how to install and start it, see Install Docker.

2. Specify Docker connection settings

1. Open the Settings / Preferences dialog (e.g. Ctrl+Alt+S) and go to the Docker page (Build, Execution, Deployment | Docker).
2. Click .
3. The connection settings depend on your Docker version and operating system:

   Docker for macOS:

   • Connect to Docker daemon with: Docker for Mac

   Docker for Windows:

   • Connect to Docker daemon with: TCP socket
   • Engine API URL: tcp://localhost:2375
   • Certificates folder: This field must be empty.

   IMPORTANT! In the General section of your Docker settings, turn on the Expose daemon on tcp://localhost:2375 without TLS option.

   

   Docker for Linux:

   • Connect to Docker daemon with: Unix socket

   Docker Toolbox for Windows or macOS:

   • Connect to Docker daemon with: Docker Machine

   The Connection successful message should appear right away. If it doesn't, check your Docker Machine executable setting on the Docker | Tools page.

   The default setting docker-machine is fine if:

   • The actual name of the executable file is docker-machine.
   • The path to the directory where the file is located is included in the environment variable Path.

   To specify an actual path to the executable file, click  and select the file in the dialog that opens.

   For more info, see Docker connection settings.

4. If you are going to map container volumes onto local host folders, note that on Windows and macOS only the local folders specified in the Path mappings section will be available for corresponding bindings. For more info, see Working with volume bindings.
5. If you are going to use Docker Compose, go to the Tools page in the Docker section (Build, Execution, Deployment | Docker | Tools) and specify the location of your Docker Compose executable. The default setting docker-compose is fine if:
   • The actual name of the executable file is docker-compose.
   • The path to the directory where the file is located is included in the environment variable Path.

   To specify an actual path to the executable file, click  and select the file in the dialog that opens.

6. Click OK in the Settings / Preferences dialog.

3. Connect to Docker

In the Docker tool window (View | Tool Windows | Docker), select a Docker node , and then click  or select Connect from the context menu.

Managing images

Pulling an image

1. In the Docker tool window, select a Docker node , and then click  or select Pull image from the context menu.

   

2. In the dialog that opens, specify:
   • Registry. The URL of the image repository service (e.g. registry.hub.docker.com for Docker Hub) or a Docker Registry configuration.
   • Repository. The image name.
   • Tag. The image tag, e.g. latest.

   

   If pulling an image assumes user authentication, click New in the Pull Image dialog to create a Docker Registry configuration and specify your Docker image repository user account info.

You can also pull and run an image using a Dockerfile, see Running an image from a Dockerfile.

Finding out the image ID

In the Docker tool window, select the image of interest. The image ID is shown on the Properties tab.

You can copy the image ID onto the clipboard by using the Copy image ID context menu command or  on the Properties tab.

Hiding untagged images

The images that have no tags, generally, are the "intermediate" ones. Usually, they are the ones that you don't want or are not ready yet to push to an image repository.

In the Docker tool window, you can hide such images:
Select the Images node or one of the images, and then click  or select Untagged images from the context menu.

Finding local images by name or ID

In the Docker tool window, you can search for images:
When in the leftmost pane, simply start typing. As a result, the text you have typed is highlighted in the names and IDs of the images and containers, if present.

Building an image

Currently, when you build an image, IntelliJ IDEA runs it automatically straight away. If it's just the image that you want to keep, delete the corresponding container.

1. Create a Dockerfile for the image that you want to build and open it in the editor.
2. To the left of FROM, click  and select Run on 'Docker'.

   

   As a result, your image is built and run in a container according to your Dockerfile.

3. Now, to delete the corresponding container, select it in the Docker tool window, and click  or select Delete container from the context menu.

You can also build an image by running the docker build command in the Terminal tool window (View | Tool Windows | Terminal).

See also, Running an image from a Dockerfile.

Pushing an image

1. In the Docker tool window, select the image that you want to upload to an image repository, and then click  or select Push image from the context menu.

   

2. If you haven't pushed to the corresponding repository yet, click New in the dialog that opens to create a Docker Registry configuration and specify your image repository user account info.
3. Specify the settings for the image that you are pushing:
   • Registry. The Docker Registry configuration to be used.
   • Repository. The name for the image that you are pushing.
   • Tag. The tag for the image that you are pushing.

   

Specifying your image repository user account info

Pushing an image to an image repository and, for certain image repositories, also pulling an image from the repository requires your logging on to the corresponding server. Your image repository user account info that you have to provide in such cases is stored in what is called a Docker Registry configuration.

You can start creating a Docker Registry configuration when pulling or pushing an image by clicking New in the Pull image or the Push image dialog. Here are the Docker Registry configuration settings:

• Address. The image repository service URL, e.g. registry.hub.docker.com for Docker Hub or quay.io for Quay.
• Username and Password. The user name and password for your user account.
• Email. The email address that you specified when creating your user account.
• Server. The name for the associated Docker connection settings (usually, Docker). They are used to connect to the service to check that your user account info is correct.

Running images

Running an image via a Docker Deployment run configuration

For running Docker images, IntelliJ IDEA provides Docker Deployment run configurations. Such a run configuration is created automatically when you:

• Run an image from the Docker tool window
• Run an image from a Dockerfile

You can also create a Docker Deployment run configuration "as usual": Run | Edit Configurations | | Docker Deployment. You may want to employ this method to run your multi-container application using a Docker Compose docker-compose.yml file.

Running an image from the Docker tool window

1. In the Docker tool window, select the image of interest, and then click  or select Create container from the context menu.

   

2. In the Create container popup, click Create.

   If you already have a Docker Deployment run configuration for your image, the Create container popup, in addition to Create, will also have the name of that run configuration as an option. By selecting the run configuration name, you can run your image according to that run configuration.

3. In the Create Deployment Configuration dialog that opens:
   • Deployment. The Docker Image option is selected. This indicates that the run configuration is based on an image available locally.
   • Image ID. Initially, this is the ID of the image for which you called the Create container command.
   • Container name. You can specify the name for the container that will be created or, otherwise, Docker will itself give your container a name.

   

   By selecting the corresponding option in the Deployment field, you can run an image or images, basing on your Dockerfile or Compose docker-compose.yml file.

4. Click Run.

Running an image from a Dockerfile

1. Open your Dockerfile in the editor.

   In the Project tool window, for Dockerfiles, there are context menu commands that you may find useful:
   Run 'Docker ...' runs the Dockerfile, creates a run configuration for it, and makes it current.
   Save 'Docker ...' saves the run configuration.
   Select 'Docker ...' makes the run configuration for the Dockerfile current, so you can run it straight away by clicking .

2. To the left of FROM, click  and select Run on 'Docker'.

   

   As a result, your image runs according to the Dockerfile and a Dockerfile-based run configuration is created.

At a later time, you can rerun your Dockerfile by selecting  | Run '<ConfigurationName>' or open the run configuration for editing by selecting  | Edit '<ConfigurationName>'.

The main settings of a run configuration associated with a Dockerfile are:

• Deployment. Your Dockerfile.
• Image Tag. The name and tag for the image that will be built, e.g. myimage:latest.
• Container Name. The name of the container that will be created. If omitted, Docker will itself give your container a name.

Viewing deployment logs

To view a deployment log - after an image is built and corresponding container is started - select the container in the Docker tool window. The log is shown in the right-hand pane on the Deploy log tab.

Converting command-line options into container settings JSON

You can convert the command-line options for the docker run command into the container settings JSON file, and use that file to configure your container at its start:

1. In the corresponding Docker Deployment run configuration, select the Container tab.
2. To the right of the JSON file field, click CLI.

   

3. In the dialog that opens, specify the options and the location of the resulting .json file.

   

Working with containers

Running commands in a container

You can run docker exec commands:

1. In the Docker tool window, right-click the container of interest and select Exec.
2. In the Run command in container popup, click Create.

   As you run the commands, IntelliJ IDEA memorizes them. So you can rerun the commands by selecting them in the Run command in container popup.

3. In the dialog that opens, type the command and click OK. For
   docker exec [OPTIONS] CONTAINER COMMAND [ARG...]
   you need to specify only the
   COMMAND [ARG...] part. For example:
   ls /tmp or mkdir /tmp/my-new-dir.

Starting a Shell or Bash session in a container

Use Exec as described earlier, i.e:

1. In the Docker tool window, right-click the container and select Exec | Create.
2. Type:
   /bin/sh or /bin/bash

   

   For Bash, instead of /bin/bash, try just bash.

3. Press Enter or click OK.

   

Finding out the container and image IDs

In the Docker tool window, select the container of interest. Its ID and the ID of its parent image are shown on the Properties tab.

You can copy the image ID, and the container ID and name onto the clipboard: select the corresponding row in the table and click . As an alternative, you can use the Copy image ID and Copy container ID context menu commands.

Renaming a container

As a result, the container is stopped and removed, and then re-created from scratch. The previous state of the container is effectively lost. The new container, most probably, will have a different ID.

1. In the Docker tool window, select the container of interest.
2. Select the Properties tab.
3. In the Container name field, specify a new name for your container, and click Save.

Inspecting a container

You can get detailed low-level information about a container in JSON format by running docker inspect:
In the Docker tool window, right-click the container of interest and select Inspect. The result is shown on the Inspection tab.

Showing container processes

To show the list of processes running in a container, right-click the container of interest in the Docker tool window and select Show processes. The result is shown on the Processes tab.

Opening a console for an ENTRYPOINT process

To see the output of the ENTRYPOINT process running inside a container, you can attach to its stdin/out:
In the Docker tool window, right-click the container and select Attach. The console will open on the Attached console tab.

Viewing the container log

When you select a container in the Docker tool window, the container log is shown on the Log tab.

Stopping a container

In the Docker tool window, select the container, and then click  or select Stop container from the context menu.

Restarting a container

In the Docker tool window, select the container, and then click  or select Redeploy from the context menu.

Rerunning an image with different settings

1. In the Docker tool window, select the container in which the image of interest runs.
2. Click  or select Edit Configuration from the context menu.
3. In the associated Docker Deployment run configuration that opens, edit the settings as necessary.
4. Click  or select Redeploy from the context menu.

Hiding stopped containers

In the Docker tool window, you can hide the containers that are not running:
Select the Containers node or one of the containers, and then click  or select Stopped containers from the context menu.

Working with volume bindings

Preparing for volume bindings on Windows and macOS

To be able to map host folders to container volumes on Windows or macOS, you should first specify corresponding path mappings:

1. Open your Docker connection settings: in the Docker tool window, select the Docker node  and click . Alternatively, Ctrl+Alt+S | Build, Execution, Deployment | Docker.

   If you are using Docker for Windows, you should start by enabling drive sharing:
   Open your Docker settings, select the Shared Drives section and then select the drive (e.g. C) that you want to make available to your containers.
   Once you've done that, restart Docker.

2. In the Path mappings section, select an existing mapping and click  to edit it, or click  to create a new mapping.

   

3. In the dialog that opens, specify the mapping:
   • Local path. The path to a local folder that you want to make available for volume bindings.
   • Virtual machine path. This is the corresponding directory path in the Docker virtual machine's file system.

   

Specifying volume bindings in a run configuration

1. Create a new Docker Deployment run configuration or open an existing one.
2. Select the Container tab and expand the Volume bindings section.
3. Click  to create a new binding.
4. In the dialog that opens, specify:
   • Container path. The path to the data volume in the container.
   • Host path. The path to the host directory that should be mounted at the specified container path.
   • Readonly. Select the checkbox to make the container volume readonly.

   

Viewing and editing volume bindings for a running container

1. In the Docker tool window, select the container and then select the Volume Bindings tab.
2. To create a new binding, click . To edit an existing one, select the binding and click .
3. Specify the settings as necessary.
4. To apply the changes, click Save.

   

   As a result, the container is stopped and removed, and then re-created from scratch. The previous state of the container is effectively lost.

   Also note that the changes are not saved in the corresponding run configuration. So, if you restart the container, e.g. , the corresponding run configuration will be rerun, and the settings specified in that run configuration will be reapplied.

Working with port bindings

You can specify the port binding settings in a Docker Deployment run configuration. Then, when your container is running, you can view and change these settings, and apply the changes.

Specifying the port binding settings in a run configuration

1. Create a new Docker Deployment run configuration or open an existing one.
2. Select the Container tab and expand the Volume bindings section.
3. To publish all the container ports, select the corresponding checkbox.
4. To specify individual bindings (the Publish all ports option in this case should be off), expand the Volume bindings section, and click  to create a new binding.
5. In the dialog that opens, specify:
   • Container port. The container port to be mapped.
   • Protocol. TCP or UDP.
   • Host IP. To make the port accessible only from your localhost, specify localhost or 127.0.0.1. To make the port accessible from other computers on your network as well, specify 0.0.0.0.
   • Host port. The corresponding host port.

   

Viewing and editing the port binding settings for a running container

1. In the Docker tool window, select the container and then select the Port Bindings tab.
2. If the container was started with the Publish all ports option on, to see the port mappings, run the Inspect command from the container's context menu, and then search the result (Ctrl+F) for "Ports".
3. To create a new binding, click . To edit an existing one, select the binding and click . If the Publish all ports option is currently on, turn it off to be able to specify individual port mappings.
4. For each particular binding, specify the settings as necessary.
5. To apply the changes, click Save.

   

   As a result, the container is stopped and removed, and then re-created from scratch. The previous state of the container is effectively lost.

   Also note that the changes are not saved in the corresponding run configuration. So, if you restart the container, e.g. , the corresponding run configuration will be rerun, and the settings specified in that run configuration will be reapplied.

Working with environment variables

The environment variables are usually set in the Dockerfile associated with the base image that you are using. There are also the environment variables that Docker sets automatically for each new container.

In a Docker Deployment run configuration, you can specify additional variables and redefine the ones that Docker sets. At a later time, when your container is running, you can view and edit the existing variables, and create and set new ones.

Specifying the environment variables in a run configuration

1. Create a new Docker Deployment run configuration or open an existing one.
2. Select the Container tab and expand the Environment variables section.
3. Click  to create a new variable.
4. In the dialog that opens, specify the variable name and value.

   

Viewing and editing the environment variables for a running container

To manage your container's environment variables, you can use your Bash shell. To open the shell: Exec from the context menu, then Create | bash.

1. In the Docker tool window, select the container and then select the Environment variables tab.
2. To create a new variable, click . To edit an existing one, select the variable and click .
3. To apply the changes, click Save.

   

   As a result, the container is stopped and removed, and then re-created from scratch. The previous state of the container is effectively lost.

Working with links

Links to other containers are specified in a Docker Deployment run configuration:

1. Open a Docker Deployment run configuration for a container that you want to link with another container.
2. Select the Container tab and expand the Links section.
3. Click  to create a new link.
4. In the dialog that opens, specify:
   • Name. Select the container you want to link to.
   • Alias. The link name alias.
5. Start the container by executing the run configuration.
6. Now, to see the link information, select Inspect from the container's context menu in the Docker tool window. Then search the inspection result (shown on the Inspection tab, Ctrl+F) for HostConfig. The link information will be shown as
   "Links" : [ "<container_name>:<link_name_alias>" ].

   Alternatively, you can open the Terminal tool window and run the following command:
   docker inspect -f "{{ .HostConfig.Links }}" <container_name>

Using Docker Compose

Running services via a Docker Deployment run configuration

1. Create a Docker Compose docker-compose.yml file and specify your services.

   In the Compose file-based Docker Deployment configurations, the settings on the Container tab are ignored.

2. Create a Docker Deployment run configuration: Run | Edit Configurations | | Docker Deployment.
3. Next to Deployment, select your docker-compose.yml file.

   

4. Execute the run configuration: .

   

Scaling a service

Scaling means changing the number of containers within a service.

1. In the Docker tool window, select the service you want to scale.

   Scaling means changing the number of containers within a service.

2. Click  or select Scale from the context menu.

   

3. Specify how many containers you want in the service.

   

Stopping and starting a service

In the Docker tool window, select the service.

• To stop the service, click  or select Stop from the context menu.
• To start the service, click  or select Start from the context menu.

  

Interacting with containers

Most of the functions that IntelliJ IDEA provides for working with "independent" containers are also available for the containers within Docker Compose services. To access these functions, use the containers' context menus and the toolbar icons in the Docker tool window. For more info, see Working with containers.

Troubleshooting

Unable to connect to Docker

Make sure that:

• Docker is running.
• Your Docker connection settings are correct.
• If you are using Docker for Windows:
  In the General section of your Docker settings, the Expose daemon on tcp://localhost:2375 without TLS option is on.
• If you are using Docker Toolbox:
  • Your Docker Machine is running.
  • The Docker Machine executable setting on the Docker | Tools page is correct.

Unable to pull an image

When trying to pull an image, you may be getting the following message:

Failed to parse dockerCfgFile: <your_home_dir>/.docker/config.json, caused by: ... {"credsStore":"wincred"}

If this is the case, go to <your_home_dir>/.docker directory and delete the file config.json.

Unable to use Docker Compose

Make sure that the Docker Compose executable setting in your Docker settings is correct.

Unable to use port bindings

Make sure that the corresponding container ports are exposed. Use the EXPOSE Dockerfile command.

My deployment log is empty

If you have another project open at the moment, you may find your deployment log in that project.

Limitations

Our Docker integration has limitations but we are working on its improvement. See the list of Docker issues in our tracking system and vote for the ones that you think should be resolved first of all.