Gentoo Docker image with distcc

![Docker Pulls]([] ![build]([] ![lint]([] ![pre-commit enabled]([] ![Renovate enabled]([] ![Conventional Commits]([]

Decrease Gentoo compilation times by leveraging spare resources, such as an Ubuntu or Windows box idling around. Docker is the only prerequisite.

[!IMPORTANT]

The SSH image variants have been deprecated as of 2025-05-16 in order to ease maintenance and reduce resource usage. No SSH images will be built moving forward. As an alternative, consider using the TCP image variants either with a *** (recommended) or a reverse SSH tunnel.

Features

• Out-of-the-box support for the following Gentoo architectures:
  • amd64
  • arm
  • arm64
  • ppc64
  • x86
• Server-side caching using ccache
• Cross-compilation support using crossdev

[!NOTE]

Only the stable toolchain of these architectures is supported.

Usage

On the worker node(s), run the containerized distcc server (distccd):

shell
docker run -d -p 3632:3632 --name gentoo-distcc --rm ksmanis/gentoo-distcc:tcp

distccd should now be accessible from all interfaces at port 3632 (0.0.0.0:3632).

[!NOTE]

Only private IP addresses are allowed to connect to distccd by default.

Command-line arguments are passed on verbatim to distccd. For instance, you can turn on the built-in HTTP statistics server:

shell
docker run -d -p 3632-3633:3632-3633 --name gentoo-distcc --rm ksmanis/gentoo-distcc:tcp --stats

The statistics server should now be accessible from all interfaces at port 3633 (0.0.0.0:3633).

For a full list of options refer to distccd(1).

Ccache

If you share a worker instance between multiple clients, you might be interested in enabling server-side caching with ccache to avoid redundant recompilations. To do so, pull the tcp-ccache tag:

shell
docker run -d -p 3632:3632 --name gentoo-distcc-ccache --rm ksmanis/gentoo-distcc:tcp-ccache

The directory /var/cache/ccache automatically persists in an anonymous Docker volume, but a named Docker volume or a bind mount may also be used for stronger persistence guarantees.

Ccache statistics can be queried as follows:

shell
docker exec gentoo-distcc-ccache ccache -sv

Crossdev

All amd64 image variants support cross-compilation for the arm64 architecture (specifically the aarch64-unknown-linux-gnu toolchain) and vice versa: all arm64 image variants support cross-compilation for the amd64 architecture (specifically the x86_64-pc-linux-gnu toolchain). In other words, an amd64 desktop can be used to cross-compile for an arm64 Raspberry Pi and vice versa.

Cross-compilation support is enabled out of the box without any user configuration. More architecture combinations can be added upon request.

Testing

A manual way to test the containers is to compile a sample C file:

c
#include <stdio.h>

int main() {
    printf("Hello, distcc!\n");
    return 0;
}

shell
DISTCC_HOSTS="127.0.0.1:3632" DISTCC_VERBOSE=1 distcc gcc -c main.c -o /dev/null