docker-alpine :: index


The musl libc implementation may work a little different than you are used to. The musl libc differences from glibc document does a really good job of outlining everything. Please take a glance at it. Here we'll talk about some of the more common things you might encounter.


One common issue you may find is with DNS. musl libc does not use domain or search directives in the /etc/resolv.conf file. For example, if you started your Docker daemon with --dns-search=service.consul, and then tried to resolve consul from within an Alpine Linux container, it would fail as the name consul.service.consul would not be tried. You will need to work around this by using fully qualified names.

Another difference is parallel querying of name servers. This can be problematic if your first name server has a different DNS view (such as service discovery through DNS). For example, if you started your Docker daemon with --dns= --dns= where is a local DNS server to resolve name for service discovery and is for external DNS resolving, you wouldn't be able to guarantee that will always be queried first. There will be sporadic failures.

In both of these cases, it can help to run a local caching DNS server such as dnsmasq, that can be used for both caching and search path routing. Running dnsmasq with --server /consul/ would forward queries for the .consul to

Incompatible Binaries

While there are binaries that will run on musl libc without needing to be recompiled, you will likely encounter binaries and applications that rely on specific glibc functionality that will fail to start up. An example of this would be Oracle Java which relies on specific symbols only found in glibc. You can often use ldd to determine the exact symbol:

# ldd bin/java
    /lib64/ (0x7f542ebb5000) => /lib64/ (0x7f542ebb5000) => bin/../lib/amd64/jli/ (0x7f542e9a0000) => /lib64/ (0x7f542ebb5000) => /lib64/ (0x7f542ebb5000)
Error relocating bin/../lib/amd64/jli/ __rawmemchr: symbol not found

In this case, the upstream would need to remove the support for this offending symbol or have the ability to compile the software natively on musl libc. Be sure to check the Alpine Linux package index to see if a suitable replacement package already exists.