Project: Netdata (Observability and Analysis / Observability)
File: building-native-packages-locally.md

This document provides instructions for developers who need to build native packages locally for testing. To build native packages locally, you will need the following: A working Docker or Podman host. A local copy of the source tree you want to build from. In the root of the source tree from which you want to build, clean up any existing files left over from a previous build and then run: ```bash docker run -it --rm -e VERSION=0.1 -v $PWD:/netdata netdata/package-builders:<tag> ``` or ```bash podman run -it --rm -e VERSION=0.1 -v $PWD:/netdata netdata/package-builders:<tag> ``` The `<tag>` should be the lowercase distribution name with no spaces, followed by the release of that distribution. For example, `centos7` to build on CentOS 7, or `ubuntu20.04` to build on Ubuntu 20.04. Note that we use Rocky Linux for builds on CentOS/RHEL 8 or newer. See for all available tags. The value passed in the `VERSION` environment variable can be any version number accepted by the type of package being built. As a general rule, it needs to start with a digit, and must include a `.` somewhere. Once it finishes, the built packages can be found under `artifacts/` in the source tree. If an error is encountered and the build is being run interactively, it will drop to a shell to allow you to inspect the state of the container and look at build logs. The environments used for building our packages are fully self-contianed Docker images built from These are published on Docker Hub with the image name `netdata/package-builders`, and tagged using the name and version of the distribution (with the tag corresponding to the suffix on the associated Dockerfile). The build code expects the following requirements to be met: It expects the source tree it should build from to be located at `/netdata`, and expects that said source tree is clean (no artifacts left over from previous builds). It expects an environment variable named `VERSION` to be defined, and uses this to control what version number will be shown in the package metadata and

Internally, the source tree gets copied to a temporary location for the build process so that the source tree can be mounted directly from the host without worrying about leaving a dirty tree behind, any templating or file movements required for the build to work are done, the package build command is invoked with the correct arguments, and then the resultant packages are copied to the `artifacts/` directory in the original source tree so they are accessible after the container exits. Build logs and artifacts can be found in the build directory, whose location varies by distribution. On DEB systems (Ubuntu and Debian), the build directory inside the container is located at `/usr/src/netdata` On RPM systems except openSUSE, the build directory inside the container is located under `/root/rpmbuild/BUILD/` and varies based on the package version number. On openSUSE, the build directory inside the container is located under `/usr/src/packages/BUILD`and varies based on the package version number. If you need to test a build for an architecture that does not match your host system, you can do so by setting up QEMU user-mode emulation. This requires a Linux kernel with binfmt\_misc support (all modern distributions provide this out of the box, but Im not sure about WSL or Docker Desktop). The quick and easy way to do this is to run the following: ```bash docker run --rm --privileged multiarch/qemu-user-static --reset -p yes ``` or ```bash podman run --rm --privileged multiarch/qemu-user-static --reset -p yes ``` This will set up the required QEMU user-mode emulation until you reboot. Note that if using Podman, you will need to run this as root and not as a rootless container (the package builds work fine in a rootless container though, even if doing cross-architecture builds). Once you have that set up, the command to build the packages is the same as above, you just need to add a correct `--platform` option to the `docker run` or `podman run` command. The current list of architectures we build for, and the correct value for the `--platform` option is: 32-bit ARMv7: `linux/arm/v7` 64-bit ARMv8: `linux/arm64/v8` 32-bit x86: `linux/i386` 64-bit x86: `linux/amd64`