Docker Run

Great! Let’s now run a Docker container based on this image. To do that we are going to use the almighty docker run command.

$ docker run busybox
$

Wait, nothing happened! Is that a bug? Well, no. Behind the scenes, a lot of stuff happened. When you call run, the Docker client finds the image (busybox in this case), loads up the container and then runs a command in that container. When we run docker run busybox, we didn’t provide a command, so the container booted up, ran an empty command and then exited. Well, yeah - kind of a bummer. Let’s try something more exciting.

$ docker run busybox echo "hello from busybox"
hello from busybox

Nice - finally we see some output. In this case, the Docker client dutifully ran the echo command in our busybox container and then exited it. If you’ve noticed, all of that happened pretty quickly. Imagine booting up a virtual machine, running a command and then killing it. Now you know why they say containers are fast! Ok, now it’s time to see the docker ps command. The docker ps command shows you all containers that are currently running.

$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES

Since no containers are running, we see a blank line. Let’s try a more useful variant: docker ps -a

$ docker ps -a
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                      PORTS               NAMES
305297d7a235        busybox             "uptime"            11 minutes ago      Exited (0) 11 minutes ago                       distracted_goldstine
ff0a5c3750b9        busybox             "sh"                12 minutes ago      Exited (0) 12 minutes ago                       elated_ramanujan
14e5bd11d164        hello-world         "/hello"            2 minutes ago       Exited (0) 2 minutes ago                        thirsty_euclid

So what we see above is a list of all containers that we ran. Do notice that the STATUS column shows that these containers exited a few minutes ago.

You’re probably wondering if there is a way to run more than just one command in a container. Let’s try that now:

$ docker run -it busybox sh
/ # ls
bin   dev   etc   home  proc  root  sys   tmp   usr   var
/ # uptime
 05:45:21 up  5:58,  0 users,  load average: 0.00, 0.01, 0.04

Running the run command with the -it flags attaches us to an interactive tty in the container. Now we can run as many commands in the container as we want. Take some time to run your favorite commands.

Container Isolation & Ephemeral State: Try creating a file inside the container shell:

/ # touch my_test_file.txt
/ # ls

Now exit the container by typing exit and start a new container with docker run -it busybox sh:

$ docker run -it busybox sh
/ # ls

Notice that my_test_file.txt is nowhere to be found! That’s because Docker creates a fresh, isolated container instance every time. Any changes made inside a container instance do not affect your host machine or subsequent container runs.

That concludes a whirlwind tour of the mighty docker run command, which would most likely be the command you’ll use most often. It makes sense to spend some time getting comfortable with it. To find out more about run, use docker run --help to see a list of all flags it supports. As we proceed further, we’ll see a few more variants of docker run.

Before we move ahead though, let’s quickly talk about deleting containers. We saw above that we can still see remnants of the container even after we’ve exited by running docker ps -a. Throughout this tutorial, you’ll run docker run multiple times and leaving stray containers will eat up disk space. Hence, as a rule of thumb, I clean up containers once I’m done with them. To do that, you can run the docker rm command. Just copy the container IDs from above and paste them alongside the command.

$ docker rm 305297d7a235 ff0a5c3750b9
305297d7a235
ff0a5c3750b9

On deletion, you should see the IDs echoed back to you. If you have a bunch of containers to delete in one go, copy-pasting IDs can be tedious. On Linux or macOS, you can filter and remove exited containers:

$ docker rm $(docker ps -a -q -f status=exited)

However, command substitution like $(...) differs across operating systems (such as Windows PowerShell). On modern versions of Docker across all platforms, the recommended command to clean up stopped containers is docker container prune:

$ docker container prune
WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y
Deleted Containers:
4a7f7eebae0f63178aff7eb0aa39f0627a203ab2df258c1a00b456cf20063
f98f9c2aa1eaf727e4ec9c0283bcaa4762fbdba7f26191f26c97f64090360

Total reclaimed space: 212 B

One last thing that’ll be useful is the --rm flag that can be passed to docker run which automatically deletes the container once it’s exited. For one-off container runs, the --rm flag is very handy.

Lastly, you can also delete images that you no longer need by running docker rmi.