From ArchWiki
Jump to: navigation, search

Docker is a utility to pack, ship and run any application as a lightweight container.


Install the docker package or, for the development version, the docker-gitAUR package. Next start and enable docker.service and verify operation:

# docker info

If you want to be able to run docker as a regular user, add yourself to the docker group.

Warning: Anyone added to the docker group is root equivalent. More information here and here.
Note: As of linux 4.15.0-1 vsyscalls, which are required by certain programs in containers (such as apt-get), have been disabled by default in kernel configuration. To enable them again, add the vsyscall=emulate kernel parameter. More information in FS#57336.


Storage driver

The docker storage driver (or graph driver) has a huge impact on performance. Its job is to store layers of container images efficiently, that is when several images share a layer, only one layer uses disk space. The compatible option, `devicemapper` offers suboptimal performance, which is outright terrible on rotating disks. Additionally, `devicemappper` is not recommended in production.

As Arch linux ships new kernels, there is no point using the compatibility option. A good, modern choice is overlay2.

To see current storage driver, run # docker info | head, modern docker installation should already use overlay2 by default.

To set your own choice of storage driver, edit /etc/docker/daemon.json (create it if it does not exist):

  "storage-driver": "overlay2"

Afterwards, restart docker.

Further information on options is available on the user guide. For more information about options in daemon.json see dockerd documentation.

Remote API

To open the Remote API to port 4243 manually, run:

# /usr/bin/dockerd -H tcp:// -H unix:///var/run/docker.sock

-H tcp:// part is for opening the Remote API.

-H unix:///var/run/docker.sock part for host machine access via terminal.

Remote API with systemd

To start the remote API with the docker daemon, create a Drop-in snippet with the following content:

ExecStart=/usr/bin/dockerd -H tcp:// -H unix:///var/run/docker.sock

Daemon socket configuration

The docker daemon listens to a Unix socket by default. To listen on a specified port instead, create a Drop-in snippet with the following content:



Proxy configuration is broken down into two. First is the host configuration of the Docker daemon, second is the configuration required for your container to see your proxy.

Proxy configuration

Create a Drop-in snippet with the following content:

Note: This assumes is your proxy server, do not use

Verify that the configuration has been loaded:

# systemctl show docker --property Environment

Container configuration

The settings in the docker.service file will not translate into containers. To achieve this you must set ENV variables in your Dockerfile thus:

FROM base/archlinux
ENV http_proxy=""
ENV https_proxy=""

Docker provide detailed information on configuration via ENV within a Dockerfile.

Configuring DNS

By default, docker will make resolv.conf in the container match /etc/resolv.conf on the host machine, filtering out local addresses (e.g. If this yields an empty file, then Google DNS servers are used. If you are using a service like dnsmasq to provide name resolution, you may need to add an entry to the /etc/resolv.conf for docker's network interface so that it is not filtered out.

Running Docker with a manually-defined network on systemd-networkd

If you manually configure your network using systemd-networkd version 220 or higher, containers you start with Docker may be unable to access your network. Beginning with version 220, the forwarding setting for a given network (net.ipv4.conf.<interface>.forwarding) defaults to off. This setting prevents IP forwarding. It also conflicts with Docker which enables the net.ipv4.conf.all.forwarding setting within a container.

A workaround is to edit the <interface>.network file in /etc/systemd/network/, adding IPForward=kernel on the Docker host:


This configuration allows IP forwarding from the container as expected.

Images location

By default, docker images are located at /var/lib/docker. They can be moved to other partitions. First, stop the docker.service.

If you have run the docker images, you need to make sure the images are unmounted totally. Once that is completed, you may move the images from /var/lib/docker to the target destination.

Then add a Drop-in snippet for the docker.service, adding the --data-root parameter to the ExecStart:

ExecStart=/usr/bin/dockerd --data-root=/path/to/new/location/docker -H fd://

Insecure registries

If you decide to use a self signed certificate for your private registry, Docker will refuse to use it until you declare that you trust it. Add a Drop-in snippet for the docker.service, adding the --insecure-registry parameter to the dockerd:

ExecStart=/usr/bin/dockerd -H fd:// --insecure-registry


Arch Linux

The following command pulls the archlinux/base x86_64 image. This is a stripped down version of Arch core without network, etc.

# docker pull archlinux/base

See also

For a full Arch base, clone the repo from above and build your own image.

$ git clone

Edit the packages file so it only contains 'base'. Then run:

# make docker-image


The following command pulls the debian x86_64 image.

# docker pull debian


Build Debian image with debootstrap:

# mkdir jessie-chroot
# debootstrap jessie ./jessie-chroot
# cd jessie-chroot
# tar cpf - . | docker import - debian
# docker run -t -i --rm debian /bin/bash

Arch Linux image with snapshot repository

Arch Linux on Docker can become problematic when multiple images are created and updated each having different package versions. To keep Docker containers with consistent package versions, an unofficial Docker image with a snapshot repository is available. This allows installing new packages from the official repository as it was on the day that the snapshot was created.

$ docker pull pritunl/archlinux:latest
$ docker run --rm -t -i pritunl/archlinux:latest /bin/bash

Alternatively, you could use Arch Linux Archive by freezing /etc/pacman.d/mirrorlist:


Remove Docker and images

In case you want to remove Docker entirely you can do this by following the steps below:

Note: Do not just copy paste those commands without making sure you know what you are doing.

Check for running containers:

# docker ps

List all containers running on the host for deletion:

# docker ps -a

Stop a running container:

# docker stop <CONTAINER ID>

Killing still running containers:

# docker kill <CONTAINER ID>

Delete all containers listed by ID:

# docker rm <CONTAINER ID>

List all Docker images:

# docker images

Delete all images by ID:

# docker rmi <IMAGE ID>

Delete all Docker data (purge directory):

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: Doing # rm -R /var/lib/docker will left behind the btrfs subvolumes of the removed containers (Discuss in Talk:Docker#)
# rm -R /var/lib/docker

Useful tips

To grab the IP address of a running container:

$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <container-name OR id>

To list IP addresses and names of all running containers (useful for use in /etc/hosts):

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

Reason: No convoluted one-liners, write a readable script. (Discuss in Talk:Docker#)
for i in `docker ps -q | awk '{print $1}'`; do echo $(docker inspect --format="{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}" $i) $(docker ps | grep $i | awk '{print $NF}') ; done


docker0 Bridge gets no IP / no internet access in containers

Docker enables IP forwarding by itself, but by default systemd-networkd overrides the respective sysctl setting. Set IPForward=yes in the network profile. See Internet sharing#Enable packet forwarding for details.

Default number of allowed processes/threads too low

If you run into error messages like

# e.g. Java
java.lang.OutOfMemoryError: unable to create new native thread
# e.g. C, bash, ...
fork failed: Resource temporarily unavailable

then you might need to adjust the number of processes allowed by systemd. The default is 500 (see system.conf), which is pretty small for running several docker containers. Edit the docker.service with the following snippet:

# systemctl edit docker.service

Error initializing graphdriver: devmapper

If systemctl fails to start docker and provides an error:

Error starting daemon: error initializing graphdriver: devmapper: Device docker-8:2-915035-pool is not a thin pool

Then, try the following steps to resolve the error. Stop the service, back up /var/lib/docker/ (if desired), remove the contents of /var/lib/docker/, and try to start the service. See the open GitHub issue for details.

Failed to create some/path/to/file: No space left on device

If you are getting an error message like this:

ERROR: Failed to create some/path/to/file: No space left on device

when building or running a Docker image, even though you do have enough disk space available, make sure:

  • Tmpfs is disabled or has enough memory allocation. Docker might be trying to write files into /tmp but fails due to restrictions in memory usage and not disk space.
  • If you are using XFS, you might want to remove the noquota mount option from the relevant entries in /etc/fstab (usually where /tmp and/or /var/lib/docker reside). Refer to Disk quota for more information, especially if you plan on using and resizing overlay2 Docker storage driver.
  • XFS quota mount options (uquota, gquota, prjquota, etc.) fail during re-mount of the file system. To enable quota for root file system, the mount option must be passed to initramfs as a kernel parameter rootflags=. Subsequently, it should not be listed among mount options in /etc/fstab for the root (/) filesystem.
Note: There are some differences of XFS Quota compared to standard Linux Disk quota, [1] may be worth reading.

See also