Overview
This post begins a series of posts discussing a few fundamentals of getting started with Docker with the goal of being able to use Docker locally for development. This blog series begins with verifying a local installation of Docker, covers the basics of pulling a Docker repository image and then demonstrating how to run a container.
Prerequisites:
For this walk through, the following prerequisites must be met:
- Docker installed for the appropriate platform:
- Mac – Docker for Mac
- Windows with Hyper-V – Docker for Windows
- Windows with Oracle VirtualBox – Docker Toolbox
- At least 4GB of free memory (RAM)
- Available disk space for downloading repository images and running containers (for this initial post, 1GB will be more than enough)
Note: for this walk through, all commands will be illustrated in a PowerShell prompt on Windows. Alternatively, a command prompt on windows or a shell/terminal prompt for Mac can be used as desired.
Getting Started:
Before getting started with the walk through, ensure that Docker is currently running. From a shell prompt, enter the following command:
docker version
If Docker is running, both client and server version information should be returned (versions listed may be newer than the version used at the time of the blog creation):
In the scenario where Docker is not running, the client version will be returned, but an error will be displayed instead of the server version information. In this case, make sure that Docker is currently running on the host computer.
Downloading a repository image from Docker Hub
While a Docker repository image will be automatically downloaded when running a Docker container from a repository image, it is possible to declaratively download the repository image into the cache of the local Docker machine. The advantage of downloading the Docker repository image explicitly is that the image can be pulled to the Docker machine with a wired or high-speed, non-metered internet connection. Once downloaded to the Docker machine, a repository can be used repeatedly without the need for an internet connection. Downloading a Docker repository image can be done with the docker pull command as follows:
docker pull alpine:latest
This command is requesting that the ‘latest’ version of the ‘alpine’ repository image be retrieved and stored locally. Looking at the repository image on Docker Hub, several other versions (aka tags) are defined for the image. At the time of authoring this post, the latest tag is just an alias for version 3.6 of the image. If instead the version 3.1 version was needed, the command docker pull apline:3.1 would be used.
Creating and running a container from a repository image
To start an instance (container) running a specific repository image, the docker run command is used. In its simplest form, the command is:
docker run alpine:latest echo hello!
This Docker command is instructing Docker to create and run an instance of the specified repository image (‘alpine’, a lightweight Alpine Linux image in only 5MB) as a container using the tag ‘latest’. The arguments ‘echo hello!’ tell Docker that once the container is running, to execute the echo command (print to the display) with the argument ‘hello!’. After executing the echo command, the Docker container will terminate.
With no other arguments specified, Docker will look for the specified tag version of the specified repository in the local machine cache. If the image is not found, it will automatically be pulled from the Docker Hub site. If the image is found (or after downloading the missing image), the run command will create the new container from the image and execute it.
Wrapping up
Containers
Listing Docker containers
Before ending this post, what article would be worth its salt if it did not also cover cleaning up after itself. What does this mean? Well, run the following command to see what is reported:
docker ps
The docker ps command lists all the containers that are running on the machine. At this point, because only one container was executed and it terminated after the echo command executed, the list should be empty. If the list is not empty, there is still a container running.
Stopping a running Docker container
If there was a container running, the container could be stopped by running the command (where d7487d7ca87 is the Container ID value listed in the result of the docker ps command)
docker stop d7487d7ca87
Note: only the first few characters of the Container ID value are necessary. If the above Container ID was the only one running (or the other running containers did not start with the letter ‘d’) the command docker stop d would have been sufficient.
Removing a stopped Docker container
To remove a Docker container (with the Container ID of d7487d7ca87) that had previously been running and now is stopped, use the following command:
docker rm d7487d7ca87
or
docker rm d
Note: If you want to stop and remove a running container in a single command, you could instead use the parameter ‘-f’ on the docker rm command as follows:
docker rm -f d7487d7ca87
Repository Images
Listing local repository images
To list the repository images that have been downloaded locally, use the following command:
docker images
For example, on this computer the following image is available:
Removing unused local repository images
Using the above listing, the alpine image on this computer can be removed using the following ‘remove image’ command and the repository image name and tag
docker rmi alpine:latest
or this command with the Image ID (or just enough characters of the Image ID to uniquely identify a single image in the list)
docker rmi 053cde6e8953
Note: only images that are not referenced by a container can be removed.
Next Post
In the next post, access to a running container will be covered using a container running a web server as well as a high-level discussion on remotely accessing a running container.
Need help deploying or automating containers on-premise or in the cloud? Check out our Cloud & Hybrid IT offerings or reach out. We’d love to get you started.
Related Content
by Tim George