Common docker run commands explained

Most of my posts involving containers will include Portainer as a graphical front end.  I was bitten a few times with a fat fingered command going to the wrong port with the wrong name.  I've had to kill off a container and try to figure out an environment variable value, lose track of what I was doing, and try to dig around in my bash history to remind myself of what I was going to execute.  I have no problem doing this at work.  I am usually able to focus on the task at hand without significant interruption.  That is not the case at home, and certainly not while researching how to do more than just copy a command to implement a pre-built container.  But, if you want to go fast, command line is how to do it.  This blog is to cover the most common flags you will encounter when implementing a container from github or dockerhub.  Let's break down a few commands that have some common flags, and what they do.

docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant

Docker is a pretty well laid out application.  To start off this command, we invoke docker, tell docker the command it is going to perform is run, which initializes a container.  The -d flag tells it to run in the background, without this flag it can take over your terminal.  We then name the container, which makes searching for running containers much simpler.  The -v commands give the container mount points.  The /path/to/your/config:/config is for a persistent volume on the docker host that survives reboot, and it will be mounted in the container as /config.  The /etc/localtime:/etc/localtime:ro is binding the local directory to the same place in the container as a read only mountpoint.  --net=host allows all network traffic to travel through the host to the container, this prevents passing through every port.  homeassistant/home-assistant is the name of the container on the registry.

Let's go for another example with a few more common flags.

docker run \
-d \
--name plex \
-p 32400:32400/tcp \
-p 3005:3005/tcp \
-p 8324:8324/tcp \
-p 32469:32469/tcp \
-p 1900:1900/udp \
-p 32410:32410/udp \
-p 32412:32412/udp \
-p 32413:32413/udp \
-p 32414:32414/udp \
-e TZ="<timezone>" \
-e PLEX_CLAIM="<claimToken>" \
-e ADVERTISE_IP="http://<hostIPAddress>:32400/" \
-h <HOSTNAME> \
-v <path/to/plex/database>:/config \
-v <path/to/transcode/temp>:/transcode \
-v <path/to/media>:/data \
plexinc/pms-docker

This is laid out a little different to break down the commands better.  This will start a media server on your network, which needs to be authenticated within 5 minutes.  I wanted to offer that warning in case the command is run and then you can't figure out why it isn't working.  The long list of -p is the ports forwarded to the host, and tcp or udp based on the required connection type.  Since it streams video and audio, using udp is preferred on some ports to reduce network traffic.  Underneath the long list of ports, the environment variables are called out with -e.  This gives information to the container without having to implement it in a config file that gets mounted.  In a previous blog I had to bind the time on the host to the time on the container, since the timing requirements are not as tight on this server, passing through the timezone works in this scenario.  It should be able to perform some type of time lookup from within the server.  The -h command gives the server application a user friendly name.  It's much simpler to find the server on the network when it isn't some 30 character alpha-numeric string when you're adding it to a client.  This command is an excellent example of what a docker command generally looks like.

Aggregate 1
Example 1

Aggregate 2
Example 2

Not shown in the commands here are a couple that I have used in previous blogs.  The first is adding devices, which may be a requirement for some containers.  The command is --device /mountpoint of device:/mountpoint on container.  If you need privileged mode, add a :rwm to the end for read, write, and mknod.  My example is in adding a Z-Wave dongle to a container.  "docker run -d --name zwaver --net=host -v /var/lib/docker/volume/config:/config --device /dev/zwave:/dev/zwave:rwm zwaver/zwaver".  The missing piece is making sure we have our restart policy setup correctly.  --restart can have the options of "no" which is helpful if you built your own container.  Use "on-failure:#" to give it a specific number of retries, if it relies on another container, something is missing, or you need to verify a configuration.  Use "always" for a self contained, known good, container.  And finally, my favorite "unless-stopped", which is great for the containers downloaded from Dockerhub that do not require much configuration.

Aggregate 3
Full run command list

Less common commands

As home users, we are probably not incredibly concerned with internal docker DNS.  Most of what we might want to do with container to container communication can probably be accomplished with environment variables.  If you were to look at the internal network of a docker host, you may have a few dozen network connections on an internal subnet.  That internal network is where the containers are free to communicate with each other, without many restrictions.  If there is an issue with container cross talk or you need to segregate traffic between containers, new bridges can be added to segregate the traffic.  You can specify a bridge with --network=bridge if you do not want your container running on the default bridge.  This can be especially helpful with databases that need to communicate with web servers.

There are a few methods to define resource utilization, restricting the container to a certain amount of CPU, memory, and IO.  If you intend on using these commands, I suggest running without them to test utilization.  The only time I have used these is during some labs to establish functionality of the commands, but they might be helpful if you are running a ton of containers from your main workstation or mining crypto-currencies.  I've used -m to limit memory to a specific amount, usual 512m for half a GB.  For CPU usage, I've set cpu=0.25 to give it one quarter of a CPU.  I have not had to set any disk IO settings, but everything I have done is either on an SSD or a ZFS pool with a considerable amount of memory.

Aggregate 4
Limiting resources

Hopefully the information offered was enough to allow a better understanding of what is happening when a docker run command is executed.  The intention is to be a tool for a beginner on what is going on when they copy and paste a command to start a new application.  This should also help convert a docker run command into what parts need to be added to different fields in a Portainer configuration.  As computing moves further into the cloud and internet of things spaces, containers are the underlying technology making it possible.  I found the official docker labs to either offer too much information, or not enough, when I did them.  But don't take my word for it.

Aggregate 5
Docker container lab