Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Linux Tools Project/Docker Tooling/User Guide

Introduction

The Linux Tools Docker Tooling plug-ins allow a user to manage Docker Images and Containers with similar functionality found in the command-line docker command.

For details on Docker and the docker command, see the Docker web-site at http://www.docker.com

Docker Tooling Perspective

A new perspective known as the Docker Tooling Perspective is added.

LinuxToolsDockerPerspective.png

This perspective brings up three new views added:

In addition, the Docker Tooling Perspective adds the Console View and the Properties View.

The Console View is used to display logs of stdout/stderr output from Containers and in some instances, allow input to stdin. The Properties View allows clicking on various elements such as Connections, Images, and Containers and getting detailed info not readily shown in the various views mentioned above.

For example, clicking on a connection shows the following:

LinuxToolsDockerConnectionProperties.png

Docker Explorer View

Overview

The first view is a tree view of the various connections to Docker daemons. A connection to a Docker daemon is needed before any management of Docker Images or Containers can be performed. On initial start-up, there will be no connections and the Docker Explorer View will display a message regarding this. Note that the Docker Images View and Docker Containers View are controlled by the connection selected in the Docker Explorer View. They will also note there are no connections established yet.

LinuxToolsDockerExplorerViewInit.png

Clicking on the message will bring up the New Connection Wizard.

LinuxToolsNewConnectionWizard.png

The wizard allows the user to select a name for the connection and specify its location. For Linux users that have a local daemon running, this will be defaulted to the Unix socket: unix:///var/run/docker.sock. If a custom connection is desired, clicking the "Use custom connection settings" checkbox will allow the user to fill in either a unix socket address or a TCP address. On Mac or Windows systems, a TCP address will be required. Authentication may be required in which case the user should click on the "Enable authentication" check-box and fill in a path to the authentication files to use.

Once the data is filled, the user can test the connection by clicking on the "Test Connection" button or simply hit the "Finish" button.

More than one connection can be specified. To add more connections, click on the LinuxToolsNewConnectionIcon.png icon to bring up the wizard again. To delete a connection, click on the LinuxToolsRemoveConnectionIcon.png icon. To refresh the tree view, click on the LinuxToolsRefreshConnectionIcon.png icon. Refreshing may be required if the user has performed management outside of Eclipse using the docker command.

The Explorer View shows a tree view with the main nodes being the connections. Each connection opens up to reveal Images and Containers nodes which have children nodes for Images and Containers that the connection knows about. Filtering is provided. Simply click on the generic Menu options (down arrow) and click on "Customize View...". This will bring up the following dialog:

LinuxToolsExplorerFilter.png

From here one can filter out:

  • Dangling Images (intermediate images that are no longer referred to)
  • Intermediate Images (images with no repo tags that are parents of named images)
  • Stopped Containers (this includes paused Containers)
  • Top-level Images (only show the first repo tag for an Image with multiple tags)

Context Menu

For both Containers and Images in the Docker Explorer View, right-clicking on a selection brings up the context menu with tasks to perform on the selected item(s). Actions applying to multiple items are only enabled if the action can be performed on all selected items.

LinuxToolsExplorerContainerMenu.png

For Containers, one can:

  • Start selected Containers - start a stopped Container
  • Pause selected Containers - pause a running Container
  • Unpause selected Containers - continue a paused Container
  • Stop selected Containers - stop running Containers
  • Kill selected Containers - kill running Containers
  • Remove selected Containers - delete stopped Containers
  • Commit Container - commit the Container to an Image
  • Display Log - display the log for the Container
  • Remove Log - removes the log for the Container from Eclipse Console View

LinuxToolsExplorerImageMenu.png

For Images, one can:

  • Run Image - build a Container and run it
  • Push Image - push an Image to a registry
  • Tag Image - add a tag to an Image
  • Remove Tag - remove a tag from an Image with multiple tags
  • Remove Selected Images - delete selected Images

Run Image

The Run Image menu selection in the Docker Explorer View brings up the Run Image Wizard. This Wizard is different from the Build Image Wizard that is available from the Docker Images View but is similar to functionality. The difference is that the Build Image Wizard is more about low-level settings.

The first page of the Wizard allows a number of common settings:

LinuxToolsRunImageWizard1.png

The second page of the Wizard also has a number of needed settings:

LinuxToolsRunImageWizard2.png

Docker Images View

Overview

The Docker Images View is used to manage Docker Images. By default, the View shows only top-level Images that have at least one repo:tag name. The menu options allows you to see all Images by clicking the "Show all images" check-box.

LinuxToolsDockerImagesView.png

The connection used for the Docker Images View is determined by the latest selection in the Docker Explorer View. Whatever was last selected in the Docker Explorer View is queried for its connection and this is used for the Docker Images View. If there is only one connection, it is defaulted.

There are a number of toolbar actions supported in the Docker Images View:

There are also context menu actions supported:

  • Tag Image - same as the toolbar tag image action
  • Remove Tag - remove a tag from an Image with multiple repo tags

The text entry below the Connection name is used to search/filter the contents of the list. Anything typed in the filter text widget is used to match items in the list (any column) and any row without a match is excluded.

Pull Image

Pulling a Docker Image consists of requesting a repo tag or repository specification. Specifying a repository but no tag will pull all Images from that repo (for example: fedora).

The pull Wizard is used to specify the repository or repo:tag specification.

LinuxToolsDockerPullWizard.png

Once complete, the user hits the "Finish" button or hits "Cancel" to abort.

The pull of an Image may take a long time. This is because an Image may use several intermediate Images each of which may be several bytes. The Linux Tools Docker Tooling provides status jobs to monitor the download of the various Images and has an overall job created to monitor the status of the pull itself. When complete, refreshing of the Docker Explorer View and Docker Images View is automatic.

Push Image

Pushing a Docker Image consists of specifying an existing repo tag to push. By default, Images will be pushed to the default Docker registry, but if a tag contains a registry specifier in addition to repo:tag, it will be pushed to the specified registry. To specify an external or local registry, use the Tag Image function to add a new tag to an existing Image which has the registry specifier and then push that tag.

The push Wizard is used to specify the tag to push.

LinuxToolsDockerPushWizard.png

Like a pull of an Image, pushing an Image may take a long time. The Linux Tools Docker Tooling provides status jobs for the various Images being pushed (may include needed intermediate Images) and an overall job is created to monitor the status of the push job.

Create Container

Creating a Container takes an Image template and with additional options, starts a Container running a specified command. The action is only enabled when an Image has been selected in the Docker Images View.

LinuxToolsDockerCreateContainer.png

There a number of fields that can be filled in.

  • Image - the Image name to base the Container on
    • This will be filled in for you by default, but you have the option of changing it in the dialog.
  • Command - this is the command to run in the Container
    • Some Images will have a default command and this field does not have to be filled in. The Image needs to have pre-installed all the requirements of the command.
  • User - by default commands run as "root" in the Container, but you can specify another user.
    • Note that the user uid is the one set up in the Image and may overlap with uids in your host environment.
  • Working Directory - this is the working directory in the Container where the command will run
  • Environment - this is a set of NAME=VALUE pairs to set the environment in the Container (e.g. PATH=/usr/bin)
  • Host Name - desired host name for the Container
  • Domain Name - desired domain name for the Container
  • Memory - memory limit to allocate (bytes)
    • Specification can use suffixes: k,K,m,M,g,G,t,T (e.g. 10M or 5k) where capital suffixes are binary (e.g. K=1024) and lower-case are decimal (k=1000).
  • Memory Swap - total memory limit (memory + swap)
    • This must be used with memory specification and must be larger than memory. Set -1 to disable swap.
  • CPU Shares - number of CPU shares (relative weight vs other Containers)
  • CPU Set - string specifying the cgroups Cpuset to use
  • Volumes - volumes to mount in the Container
    • You can mount any host volume paths to host container paths using HOST_PATH:CONTAINER_PATH. Specifying just a path is mounting CONTAINER_PATH.
    • This can be used to access host files in the Container, essentially copying them over.
  • Port Specs - port mappings
    • Specify HOST_PORT:CONTAINER_PORT or :CONTAINER_PORT if you want the same port mapped over. A port is specified as port/protocol (e.g. 2345/tcp)
  • Exposed Ports - ports in Container to expose to the host
  • On Build - no longer used (Deprecated)
  • Entry Point - sets the entry point for the Container
  • Network Mode - allows you to select different network modes
    • Supported values are "bridge", "host", or container:<name|id>
  • Attach Stdin - attach stdin to Container
  • Attach Stdout - attach stdout to Container
  • Attach Stderr - attach stderr to Container
  • TTY - attach std streams of Container to a TTY
  • Open Stdin - open stdin on Container start
    • This is needed if you want to type input via the Console or are using a TTY.
  • Stdin Once - close stdin after the one attached client disconnects
  • Network Disabled - disable the network for the Container
  • Privileged - run in privileged mode
    • This should be used carefully as it gives the Container full access to the host.
  • Publish All Ports - allocate a random host port for all exposed ports


Build Image

Building an Image takes an existing Image and modifies it to create a new Image. Typically this involves installing new packages. The specification of the new Docker Image is done via a special file which is always named: "Dockerfile". Clicking on the Build Image icon starts the Build Image Wizard:

LinuxToolsDockerBuildImage.png

There are two fields that need to be filled in:

  • Name - this is the name that will be given to the new Image
    • Note that this name must follow correct repo:tag format.
  • Directory - this is the directory that contains or will contain the Dockerfile

The directory can be specified using the "Browse" button. Once a valid existing directory is specified, the "Edit" button will be enabled, allowing creation and modification of the Dockerfile using a basic editor dialog.

When the Dockerfile is considered complete, hitting the "Finish" button will start the Image build action. When the build is complete, the Docker Images View will be refreshed automatically.

Dockerfile Editor

LinuxToolsDockerfileEditor.png

The Dockerfile editor is a rudimentary text editor with clipboard support (copy, cut, and paste). The Dockerfile is used to specify how to build the new Docker Image. The file contains a set of commands used to build the Image:

  • FROM xxxxxx - this must be the first line and specifies the Image xxxxxx to base off of (e.g. FROM fedora:20)
    • The first line of the file must be: FROM: xxxxxx where xxxxxx is the Docker Image name/id to base the Image off of (e.g. FROM: fedora:20).
  • MAINTAINER name - this sets the Author field of the Image and is optional
  • RUN <cmd | ["executable", "arg0", "arg1" ...]> - this is a command that is run to modify the base Image in either the cmd format or the executable format
    • The cmd form is run in a shell (/bin/sh -c cmd).
    • Typically, this is how you install new packages (e.g. RUN yum install -y gdb). It can also be used to modify the configuration (e.g. sed operations on a config file).
    • These commands are run in the build stage prior to any Container being run and there can be multiple RUN commands specified.
  • CMD - this is the default command that the new Image will run if one isn't specified on Container create.
    • There are three forms:
    • The CMD is not run in build, but only when the Container is created and started.
  • ENV - this specifies one of more environment variables
    • There are two forms:
      • <NAME> <VALUE>
      • <NAME>=<VALUE> <NAME2>=<VALUE2> ...
    • The second format allows multiple environment variables at once. There can be multiple ENV specifiers.
    • Once specified, the environment variable may be referred to later on using the $NAME syntax (e.g. HOME=/home/$USER)
  • LABEL - adds metadata to the Image
  • ONBUILD - use this to specify commands to add to any Image building from this one
    • This is useful for configuration stuff that needs to be done repeatedly in each child Image.
  • ADD - add a file from the host into the Container file system
    • There are two forms:
      • ADD <src>... <dest>
      • ADD ["<src>"... "<dest>]
    • The second form is used to quote names that have white-space.
  • COPY - copy a file from host into the Container file system
    • There are two forms:
      • COPY <src>... <dest>
      • COPY ["<src>"... "<dest>]
    • The second form is used to quote names that have white-space.

For more details, see the official Dockerfile reference

Tag Image

The Tag Image dialog can be brought up directly from the Docker Images View toolbar or using the context menu by right-clicking on an Image.

LinuxToolsDockerTagImageDialog.png

The dialog is simple and asks for a new tag to add to the Image. The tag should be of one of two forms:

  • <repository>:<tag> where <repository> may be <username/reponame> or <reponame>
  • <registry>:<repository>:<tag> where <registry> contains a "." or ends with a port specifier (":port")

Adding a tag with a registry is the way to push existing Images to local or external registries. By default, Docker pushes Images to its default registry. When pushing to the default registry, a username needs to be specified in the repository specifier because write privileges are prohibited for the base Images (e.g. fedora:20 is the official Docker Image for F20 whereas a user may have a user/fedora:20 copy they have modified).

Remove Tag

LinuxToolsDockerRemoveTag.png

The Remove Tag dialog allows the user to remove a tag from an existing Image. This may be done to rename a tag or to keep the number of tags manageable. The Remove Tag menu item is only enabled after selecting an existing Image in the Docker Images View that has multiple tags. The dialog presents the list of possible tags to remove in a drop-down list.

Docker Containers View

Overview

The Docker Containers View is used to manage Docker Containers. By default only running Containers are shown. To see all Containers, click on the menu options and click the "Show all containers" check-box.

LinuxToolsDockerContainersView.png

The connection used for the Docker Containers View is determined by the latest selection in the Docker Explorer View. Whatever was last selected in the Docker Explorer View is queried for its connection and this is used for the Docker Containers View. If there is only one connection, it is defaulted.

The text entry below the Connection name is used to search/filter the contents of the list. Anything typed in the filter text widget is used to match items in the list (any column) and any row without a match is excluded.

There are a number of toolbar actions supported in the Docker Containers View:

  • LinuxToolsDockerContainerStartIcon.png - start a stopped Container
  • LinuxToolsDockerContainerPauseIcon.png - pause a running Container
  • LinuxToolsDockerContainerUnpauseIcon.png - continue running a paused Container
  • LinuxToolsDockerContainerStopIcon.png - stop a running Container
  • LinuxToolsDockerContainerKillIcon.png - kill a running Container
  • LinuxToolsDockerContainerDeleteIcon.png - delete a stopped Container
  • LinuxToolsDockerContainerRefreshIcon.png - refresh Containers list

It should be noted that the various actions above are enabled/disabled based on the state of the current selected Container(s) in the View. Multiple Containers can be selected for an action so long as all Containers meet the enablement requirements.

  • a Container can only be started if it is stopped with a known status
  • a Container can only be stopped, paused, or killed, if it is known to be running
  • a Container can only be unpaused if the Container is known to be paused
  • a Container with unknown/missing status can only be deleted

The following context menu actions are supported:

Commit Container

The Commit Container dialog is simple.

LinuxToolsDockerCommitContainer.png

The user is required to enter:

  • Name - name of the new Image being created
    • The name must be a valid repo tag name.
  • Author - optional name to add as the Author of the Image
  • Comment - optional comment to add for the Image

Display Log

The Display Log action opens a console in the Console View with the stdout/stderr output for the Container.

LinuxToolsDockerDisplayLog.png

In the example above, each entry in the log is preceded by a time-stamp. This can be controlled using Window->Preferences->Docker->Logging.

LinuxToolsDockerLoggingPreferences.png

From there, one can control:

  • logging on start - by default starting a Container will output stdout/stderr to a console in the Console View
    • Each log is in a separate console that can be removed using the Remove Log context menu-item for the Container
  • timestamps - by default they are added

Properties View

The Properties View will respond to selections in the three Docker Tooling Views: Docker Explorer View, Docker Images View, and the Docker Containers View. The data shown will depend on what is being selected:

  • Docker Connection
  • Docker Image
  • Docker Container

LinuxToolsDockerConnectionProperties.png

For a Docker Image and Docker Container, there are two forms of data:

  • Info - what is shown from the docker command when listing Images or Containers
  • Inspect - what is shown from the docker command when inspecting an Image or Container (additional data)

LinuxToolsDockerPropertiesView.png

Back to the top