IntelliJ IDEA 2017.3 Help

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 new.
  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.

    03 DockerSettings

    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.

    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 browseButton 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 iconDocker, and then click run or select Connect from the context menu.

51 DockerConnected

Managing images

Pulling an image

  1. In the Docker tool window, select a Docker node iconDocker or the Images node, and then click iconPullImageDocker or select Pull image from the context menu.
    52 DockerPullImage
  2. In the dialog that opens, specify:
    • Registry. The URL of the image repository service (by default, registry.hub.docker.com for Docker Hub) or a Docker Registry configuration.
    • Repository. The image name.
    • Tag. The image tag, e.g. latest.
    53 DockerPullImageDialog

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.

54 DockerImageID

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

Hiding untagged images

Images with no tags (<none>:<none>) can be one of the following:

  • Intermediate images serve as layers for other images and do not take up any space.

  • Dangling images remain when you rebuild an image based on a newer version of another image.

    Dangling images should be pruned, because they take up space.

To hide untagged images, click the Filter menu on the Docker toolbar, and then click Show Untagged Images to remove the check mark.

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.

55 DockerFindImage

Building an image

Docker can build images by reading instructions from a Dockerfile. When the Dockerfile is open in the editor, click runTwoGreenArrows in the gutter and select to build the image on a specific Docker node.

56 DockerfileBuild

You can also build the image using docker build in the Terminal tool window (View | Tool Windows | Terminal).

For information about running images, see 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 iconPushImageDocker or select Push image from the context menu.
    57 DockerPushImage
  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.
    58 DockerPushDialog

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 (by default, 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.
59 DockerRegistryDialog

Running images

IntelliJ IDEA uses run configurations (Run | Edit Configurations |) to run Docker images. There are three types of Docker run configurations:

Running an image from the Docker tool window

  1. In the Docker tool window, select the image of interest, and then click iconCreateContainerDocker or select Create container from the context menu.
    62 DockerCreateContainer
  2. In the Create container popup, click Create.
  3. In the Create Docker Configuration dialog that opens:
    • 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.
    63 DockerImageDeployment
  4. Click Run.

Running an image from a Dockerfile

  1. Open your Dockerfile in the editor.
  2. Click runTwoGreenArrows in the gutter and select to run the image on a specific Docker server. If there is an existing configuration for the image, you can run this configuration or edit it.
    56 DockerfileRun

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

  • Image Tag. Custom name and optional tag for the image that will be built, for example my-image:latest.
  • Container Name. The name of the container that will be created. If omitted, Docker will itself give your container a name.
61 DockerfileRunConfig

Viewing logs

After an image is built and the corresponding container is started, select the container in the Docker tool window and open one of the following tabs in the right-hand pane:

  • Deploy log shows log messages from the run configuration

    65 DockerDeploymentLog
  • Log shows log messages from the running container

    65 DockerContainerLog

Adding command-line options for the container

When running a container on the command line, the following syntax is used:

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

All optional parameters can be specified in the corresponding Docker run configuration fields.

  • Options are specified in the Command line options field. In the previous screenshot, the container is connected to the my-net network and is assigned an alias my-app.

  • Commands and arguments to be executed when starting the container are specified in the Entrypoint and Command fields. These fields override the corresponding ENTRYPOINT and CMD instructions in the Dockerfile. In the previous screenshot, when the container starts, it executes the docker-entrypoint.sh script with postgres as an argument.
66 DockerContainerCLI

The Command preview field shows the actual Docker command used for this run configuration.

You can also use the run configuration to bind volumes and ports, set environment variables and build-time arguments.

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.
  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
    67 DockerExecBinBash
  3. Press Enter or click OK.
    67 DockerExecBinBash 1

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 copy. As an alternative, you can use the Copy image ID and Copy container ID context menu commands.

Renaming a container

  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.

68 DockerInspect

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 stop or select Stop container from the context menu.

Restarting a container

In the Docker tool window, select the container, and then click deploymentConsoleDeployAll 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 edit config docker or select Edit Configuration from the context menu.
  3. In the associated Docker run configuration that opens, edit the settings as necessary.
  4. Click deploymentConsoleDeployAll or select Redeploy from the context menu.

Hiding stopped containers

By default, the Docker tool window displays all containers, including those that are not running. To hide stopped containers from the list, click the Filter menu on the Docker toolbar, and then click Show Stopped Containers to remove the check mark.

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 iconDocker and click edit config docker. Alternatively, Ctrl+Alt+S | Build, Execution, Deployment | Docker.
  2. In the Path mappings section, select an existing mapping and click edit1 to edit it, or click add to create a new mapping.
    69 Docker path mappings
  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.
    69 Define path mapping

Specifying volume bindings in a run configuration

Docker can mount a file or directory from the host machine to the container using the -v or --volume option. You can configure this in the Docker run configuration using the Bind mounts field.

In the Bind Mounts dialog, you can create a list of bindings by specifying the host directory and the corresponding path in the container where it should be mounted. Select Read only if you want to disable writing to the container volume.

69 DockerVolumeBindings

The Bind mounts field shows the configured volume bindings. For example, if you want to mount some local PostgreSQL data directory (/etc/pg-data) to the PostgreSQL data directory inside the container (/var/lib/pgsql/data), this can be configured as illustrated on the previous screenshot.

If you expand the Command preview field, you will see that the following line was added:

-v /etc/pg-data:/var/lib/pgsql/data

This can be used in the Command line options field instead of creating the list of volume bindings using the Bind Mounts dialog.

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 add. To edit an existing one, select the binding and click edit1.
  3. Specify the settings as necessary.
  4. To apply the changes, click Save.
    70 DockerVolumeBindingsTomcatDTW

Working with port bindings

You can specify the port binding settings in a Docker 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

Docker can map specific ports on the host machine to ports in the container using the -p or --publish option. This can be used to make the container accessible from outside. In the Docker run configuration, you can select to expose all container ports to the host or use the Bind ports field to specify port mapping.

In the Port Bindings dialog, you can create a list of bindings by specifying which ports on the host should be mapped to which ports in the container. You can also provide a specific host IP from which the port should be accessible (for example, you can set it to 127.0.0.1 to make it accessible only locally, or set it to 0.0.0.0 to open it for all computers in your network).

71 DockerPortBindings

The Bind ports field shows the configured port bindings. For example, if you already have PostgreSQL running on the Docker host port 5432, you can map port 5433 on the host to 5432 inside the container as illustrated on the previous screenshot. This will make PostgreSQL running inside the container accessible via port 5433 on the host.

If you expand the Command preview field, you will see that the following line was added:

-p 5433:5432

This can be used in the Command line options field instead of creating the list of port bindings using the Port Bindings dialog.

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 add. To edit an existing one, select the binding and click edit1. 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.
    72 DockerPortBindingsTomcatDTW

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 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

Docker can define environment variables for the container using the -e or --env option. You can configure this in the Docker run configuration using the Environment variables field.

In the Environment Variables dialog, you can create a list of names and values for variables.

73 DockerEnvVar

The Environment variables field shows the configured variables. For example, if you want to connect to PostgreSQL with a specific user name by default (instead of the operating system name of the user running the application), you can define the PGUSER variable as illustrated on the previous screenshot.

If you expand the Command preview field, you will see that the following line was added:

--env PGUSER=pg-admin

This can be used in the Command line options field instead of creating the list of names and values using the Environment Variables dialog. If you need to pass sensitive information (passwords, secrets, etc.) as environment variables, you can use the --env-file option to specify a file with this information.

Viewing and editing the environment variables for a running container

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

Specifying build-time variables

Docker can define build-time values for certain environment variables that do not persist in the intermediate or final images using the --build-arg option for docker build. These must be specified in the ARG instruction of the Dockerfile with a default value. You can configure build-time variables in the Docker run configuration using the Build args field.

For example, you can use build-time variables to build the image with a specific version of PostgreSQL. To do this, add the ARG instruction to the beginning of your Dockerfile:

ARG PGTAG=latest FROM postgres:$PGTAG

The PGTAG variable in this case will default to latest if you do not redefine it as a build-time variable. So by default, this Dockerfile will produce an image with the latest available PostgreSQL version. However, you can use the Build Args dialog to redefine the PGTAG variable.

74 DockerBuildArgs

In the previous screenshot, PGTAG is set to 9, which will instruct Docker to pull postgres:9. When you build and run the image now, it will start the container with latest PostgreSQL 9 version. To check this, execute postgres --version inside the container and see the output; it should be postgres (PostgreSQL) 9.6.6 or some later version.

If you expand the Command preview field, you will see that the following option was added to the docker build command:

--build-arg PGTAG=9

Using Docker Compose

Running services via a Docker run configuration

  1. Create a Docker Compose docker-compose.yml file and specify your services.
  2. Create a Docker-compose run configuration: Run | Edit Configurations | add | Docker .

    64 DockerComposeDeployment
  3. Specify your docker-compose.yml file in the Compose file field.
  4. Execute the run configuration.

Scaling a service

  1. In the Docker tool window, select the service you want to scale.
  2. Click IconDockerScaleService or select Scale from the context menu.
    96 DockerComposeScaleService
  3. Specify how many containers you want in the service.
    97 DockerComposeServiceScaled

Stopping and starting a service

In the Docker tool window, select the service.

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

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:

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.

Last modified: 22 January 2018

See Also