As a container framework, Docker is hard to beat for its easy of use and simplicity. However, what appears simple is normally hiding a layer of complexity, and sometimes as developers we have to delve beneath the surface to see what’s really happening.
In this blog post I’ll be touching on the docker commands beyond the docker ps and docker run basics. As Docker becomes more embedded in your projects, it’s important to know about some of following commands to make sure you’re taking advantage of everything Docker has to offer.
1. docker stats
Usage: docker stats [OPTIONS] [CONTAINER…]
Check the resource usage of containers running on your server using docker stats. Output is updated in real time, so it’s ideal for making sure containers are behaving over time or during a specific event (e.g. deployment).
docker stats
Next level: you can use the –format option to provide your own output format as a Go template. For example, if we were only interested in memory usage we could run the following command to print the memory usage for each container:
docker stats --format "{{.Container}}: {{.MemUsage}}"
2. docker cp
Usage: docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH
If you want to copy a specific file from a container, you can do that with docker cp.
Let’s say I have a container running a Java jar file, and I want to inspect the contents of that.
I can just copy the file out of the container with:
docker cp <container-name>:/springbootify.jar .
Next level: you can also copy in the other direction by just switching around the order of the parameters, like this:
docker cp some-other-file.txt <container-name>:/
Tip: if you’re running Git Bash in MinTTY mode on Windows like me, when executing a docker exec type command, as above, you’ll need to prepend it with winpty.
3. docker tag and docker push
Usage: docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
Usage: docker push [OPTIONS] NAME[:TAG]
These commands can be used to push your image to an external repository, so that it can be later run on another server. docker tag is what we use to define which repository an image will be pushed to, and docker push is the command that does the upload itself.
Let’s assume I have the following image that I want to push to a remote repository, in this case within my Docker Hub account:
I can issue the docker tag command to tag the same image with details of my Docker Hub repository:
docker tag gradle-docker-example:0.1.0 <docker-hub-username>/gradle-docker-example:0.1.0
Note that the image id remains the same between the 2 versions of the image. You can think of it as the same image, just with 2 references.
I can then push the image with docker push <repository-name>:<tag>
4. docker diff
Usage: docker diff CONTAINER
Really useful to see how a container’s file system has changed since it was created. If we copy a file into a container (see docker cp, above) then do the docker diff <container-name>, you’ll see the file appear in the output.
5. docker system df and docker system prune
Usage: docker system df [OPTIONS]
Usage: docker system prune [OPTIONS]
Docker can use a lot of disk space with all the images it downloads.
docker system df will show you how much disk space you’re using and how much can be potentially reclaimed.
Once you’ve identified an area to be cleaned up, run docker system prune which will remove:
- all stopped containers
- all networks not used by at least one container
- all dangling images
- all build cache
Tip: a dangling image is an unreferenced image identified with repository <none> and tag <none> when running the docker images command. They may build up over time but can safely be removed.
Next level: add the -a option to make docker also remove images that are no longer referenced by running containers. Probably a helpful option to use in most scenarios, to reclaim large amounts of space.
6. docker commit
Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]
You can create a new image from an existing container with docker commit. This will include all changes that have been made to the container’s file system, making this a useful command if you want to keep a version of a container for debugging purposes.
In the example below I’ve copied a file some-other-file.txt into a running container (see docker cp), verified that the file is showing up, then committed the container to a new image tag, version-with-file.
I can now run the image as normal, and verify that the expected file some-other-file.txt is present.
7. docker search
Usage: docker search [OPTIONS] TERM
If you’re at home in a terminal window like me, you might not want to use a browser to search for image, so instead use docker search.
Here I’m searching for Jenkins using docker search jenkins:
Next level: as expected, you can use all sorts of filters to refine your results. Here I’m showing only images that have a minimum of 100 stars and limiting the result count to 3, using docker search –filter stars=100 –limit 3 jenkins
8. docker top
Usage: docker top CONTAINER [ps OPTIONS]
If you want to quickly see what processes are running inside your container, use docker top. Below you can see I have 2 process running.
The process ID (or PID) shown here is from the point of view of the host rather than the container. If you ran top inside the container yourself, the PIDs would be quite different. These represent the same processes, but the PIDs have been changed to effectively hide the host information from the container.
9. docker export and docker import
Usage: docker export [OPTIONS] CONTAINER
Usage: docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]
In the scenario where you might want to pull the state of a container from a server you may need to use docker export and docker import. This would allow you to create an archive that you can transfer to another server.
Here I’m running docker export <container-name> > <tar-file-name> to create an archive from a container.
Having removed all my local images (to prove the import works), I can now run docker import <tar-file-name> to create an image from the container archive.
Tip: if you want to export an image rather than a container, look into docker save and docker load.
10. docker exec
Usage: docker exec [OPTIONS] CONTAINER COMMAND [ARG…]
Sometimes you want to run an additional process in a container on top of what is already running. In that case, you can use docker exec to run any command you want, and even start up a new bash session.
In the following example, I’ve run winpty docker exec -it <container-id> bash to start a bash session in an existing Ubuntu container. This then allows me to run any command I want, interactively:
Info: because I’m running all this from Git Bash on Windows I have to also include the winpty command. You can most likely just run winpty docker exec -it a5 bash
Bonus command: Windows container break-out
If you’re running Docker for Windows, you’ll probably know that docker is running inside a Linux VM. You can see this VM if you go to Hyper-V Manager.
A fun discovery I made in writing this blog post was that there’s a way to gain access to this VM. Normally you can’t easily access it, as it doesn’t have ssh enabled. To get around this, run the following docker image:
winpty docker run -it --rm --privileged --pid=host justincormack/nsenter1
Now I have full access to the VM itself, which you could use, for example, to check PIDs.
Not exactly a command, but useful nonetheless!
Conclusion
Hopefully you can now see beyond the docker ps and docker images commands, and might be able to use a few of these more specialist commands in your everyday dealings with Docker.
This is by no means an exhaustive list, so do check out the extensive documentation over at docs.docker.com for all the commands.
