Distribute application as docker image

kj4tmp · March 31, 2025, 12:44am

I am building an executable that I would like to distribute as a docker image.

It is beautifully statically linked etc, so docker doesn’t really add anything to it except as a convenient downloading mechanism for the user.

My question is how to integrate the building of this image into my project.

Should I:

Use the zig build system to add a system command that build the image?
Put zig inside a docker container and add a bash script to my CI?

Are there any examples out there of people producing docker images from a zig project?

sbrow · March 31, 2025, 3:54am

I’m not really a docker guy, but if you don’t really care about the contents of the container, then just COPY the resulting binary into PATH and be done with it.

If you care about the layering of your image, then including the zig tool chain and building from source inside the container might work better, but again - not a docker expert.

yataro · March 31, 2025, 5:18am

I don’t think using Zig build system to build Docker images is a good idea, it will change global state: pull Docker images, save built image to local registry. So I believe Docker “build system” should not be integrated to your build.zig.

It is common to build your software with Docker, to ensure system libraries are compatible with container (Zig can target selected glibc version and can link musl statically so this is only valid for other system libraries). For example:

Dockerfile

FROM alpine:3.21.2 AS build

RUN set -x; apk add --no-cache zig;

RUN set -x; mkdir -p ~/build;

WORKDIR /root/build
COPY main.zig .

RUN set -x; zig build-exe main.zig --name zigservice

FROM alpine:3.21.2

RUN set -x; mkdir -p /opt/zigservice/

COPY --from=build /root/build/zigservice /opt/zigservice/zigservice

ENTRYPOINT [ "/opt/zigservice/zigservice" ]

main.zig

const std = @import("std");

pub fn main() void {
    std.debug.print("Hello World!\n", .{});
}

Build it with docker build -t zigservice . and run it with docker run --rm zigservice.

But if you don’t link system libraries, simple bash script can be used, and its content usually something like:

zig build-exe main.zig --name zigservice
docker build -t zigservice .

Dockerfile

FROM alpine:3.21.2

RUN set -x; mkdir -p /opt/zigservice/

COPY zigservice /opt/zigservice/zigservice

ENTRYPOINT [ "/opt/zigservice/zigservice" ]

Pros of building with Docker also include: dependencies are fetched in “builder” container, no configuration required on host machine, easy to build for almost any Linux system, no need to setup cross-compilation sysroot when program must use system libraries (useful on Windows).

EDIT: I used zig build-exe as a simple example of building, zig build will work the same way.

kj4tmp · April 2, 2025, 3:27am

Tigerbeetle appears to be building a script and running it, executing system commands to build and push the docker image:

github.com/tigerbeetle/tigerbeetle

src/scripts/release.zig

02c990121


      
          fn publish_docker(shell: *Shell, info: VersionInfo) !void {
              var section = try shell.open_section("publish docker");
              defer section.close();
          
              assert(try shell.dir_exists("zig-out/dist/tigerbeetle"));
          
              try shell.exec(
                  \\docker login --username tigerbeetle --password {password} ghcr.io
              , .{
                  .password = try shell.env_get("GITHUB_TOKEN"),
              });
          
              try shell.exec(
                  \\docker buildx create --use
              , .{});
          
              for ([_]bool{ true, false }) |debug| {
                  const triples = [_][]const u8{ "aarch64-linux", "x86_64-linux" };
                  const docker_arches = [_][]const u8{ "arm64", "amd64" };
                  for (triples, docker_arches) |triple, docker_arch| {

This file has been truncated. show original

sbrow · April 2, 2025, 2:01pm

@yataro If Tigerbeetle is doing it, you should take note. Those guys really know what they’re doing.

yataro · April 2, 2025, 2:34pm

I have no doubt in tigerbeetle guys competence, but I still don’t think that is good thing to do. Considering example with Docker as builder (this is a must when using of system libraries, due to ABI and stuff). Docker as builder scenario does not really fit here.

Tigerbeetle case is fine, they don’t need to build it inside a Docker container, their Dockerfile is a single COPY. The way Zig build system utilized there can be supported by fact that the same build system is used to build program, and built program is the dependency of Docker container build, which fits nicely.
I still don’t like an idea of utilizing Zig build system for this, but it is only my personal preference.

I would use the moment to say that blunt appeal to authority is not very good for decision making . I just shared my opinion and example when using Zig build system to build a Docker container rather redundant (Docker as builder). In such case Zig build system would be used as a script runner, imposing a dependency, while the idea of Docker as builder is to have no build dependency but Docker itself.

sbrow · April 2, 2025, 11:51pm

I was just trying to add context. If you unsure about something, copying what someone reputable is doing is a good place to start. Obviously I advocate always, always trying things yourself and forming your own opinions.

Personally, I can hardly imagine building anything without using nix, but that’s a whole journey to go on which is likely more effort than most are willing to invest.

The nixos-generators package outputs really nice, compact docker images with no in-container OS dependencies. But again, it’s a whole can of worms.

If your CI already builds a binary, you probably just want to add a step after that to copy the binary into a docker container and call it a day.