Packaging Static Installer

Building a static Netdata binary

The static build produces a self-extracting installer (netdata-<arch>-latest.gz.run) for a compatible Linux system matching the selected architecture, including supported 32-bit ARM targets. It installs under /opt/netdata without requiring a native build toolchain on the target.

Loading this skill does not authorize image pulls/removal, submodule changes, privileged host registration, builds, extraction or target installation. An authorized build may involve those build prerequisites: inspect the concrete requirements and apply existing authorization. Preserve unrelated submodule work and existing artifacts before any operation that would replace them. Building an artifact alone does not authorize deploying it.

Timing, size and slowdown figures below are historical observations, not build or compatibility guarantees.

TL;DR — x86_64 native

# 1. Pre-flight for an authorized build (inspect first; honor pinned reproduction inputs)
# Initialize only missing required submodules using Gotcha #1 below.
# For a normal build, refresh the image; retain the selected image for a pinned reproduction.
docker pull netdata/static-builder:v1     # see Gotcha #2

# 2. Build (~22-25 min cold, ~10-15 min on cache hit, on a 24-core host)
./packaging/makeself/build-static.sh x86_64

# 3. Output
ls -la artifacts/
# artifacts/netdata-x86_64-latest.gz.run        historically ~190 MB; matching compatible x86_64 Linux target
# artifacts/netdata-x86_64-vX.Y.Z-N-nightly.gz.run
# artifacts/netdata-latest.gz.run               (x86_64 only — alias of the above)
# artifacts/netdata-vX.Y.Z-N-nightly.gz.run     (x86_64 only — alias)

For debug builds: ./packaging/makeself/build-static.sh x86_64 debug.

What you actually run

The orchestrator is packaging/makeself/build-static.sh, which:

1. Translates the architecture name (x86_64, aarch64, armv6l, armv7l) to a docker --platform value via packaging/makeself/uname2platform.sh.
2. Sets per-arch tuning flags (packaging/makeself/build-static.sh:27-56):
   • x86_64 → -march=x86-64 baseline (distinct from the Nehalem-v2 QEMU CPU choice), GOAMD64=v1.
   • aarch64 → -march=armv8-a, Cortex-A53, GOARM64=v8.0.
   • armv7l → -march=armv7-a, Cortex-A7, GOARM=7.
   • armv6l → -march=armv6zk -mtune=arm1176jzf-s, ARM1176, GOARM=6.
3. Registers binfmt/QEMU on the container host using a privileged container when cross-arch emulation is needed. Existing registration or SKIP_EMULATION skips that operation.
4. Pulls netdata/static-builder:v1 if missing locally; removes a mismatched-platform image first.
5. Bind-mounts $(pwd) into the container at /netdata and runs /netdata/packaging/makeself/build.sh inside it.

The container then runs packaging/makeself/run-all-jobs.sh, which executes packaging/makeself/jobs/*.sh in lexical order:

Source files: packaging/makeself/build-static.sh, packaging/makeself/build.sh, packaging/makeself/run-all-jobs.sh, packaging/makeself/functions.sh, packaging/makeself/jobs/.

Pre-flight (DO NOT SKIP)

For an authorized build, establish these prerequisites before spending build time. The launcher bind-mounts the checkout writable and replaces generated artifacts; preserve existing results that must survive the build.

Gotcha #1: submodules must be initialized

The build configures with CMake against vendored sources at:

• src/aclk/aclk-schemas/
• src/collectors/debugfs.plugin/libsensors/vendored/

If either is empty, CMake aborts after ~2 min with:

Cannot find source file: vendored/lib/access.c
No SOURCES given to target: vendored_libsensors
ABORTED  Failed to configure Netdata sources.

A plain fresh clone or linked worktree may have uninitialized submodules. Inspect git submodule status and local submodule changes first. Initialize missing required sources for the authorized build; do not reset modified or divergent submodules merely to make the status clean. For each required path listed above whose status begins with -, set missing_required_submodule to that exact path in the same shell invocation as the command below. Repeat that assignment and command once per selected path; do not assume shell variables persist across separate tool calls:

git submodule update --init -- "${missing_required_submodule:?set one uninitialized required submodule path}"

The path argument confines initialization to the selected missing module. Do not use an unscoped or recursive update: that can move already initialized modules to recorded commits, including unrelated or deliberately divergent modules.

Verify with git submodule status: - means uninitialized, + differs from the recorded commit, and U is conflicted. A leading space confirms the recorded commit, not the absence of local edits. Investigate differences before proceeding.

Gotcha #2: refresh the cached docker image

The launcher pulls the target-platform image only when it is missing; it removes a cached image with a mismatched platform first. A previously observed stale image failed checksum verification with:

sha256sum: unrecognized option: c
SHA256 verification of tar file libnetfilter_acct-1.0.3.tar.bz2 failed (rc=1)
expected: <hash>, got <same-hash>

functions.sh uses sha256sum --c --status; an implementation lacking that option can fail despite matching bytes. This symptom is evidence to inspect the image/tool, not proof of a specific Alpine version. For a normal build session, refresh the intended platform's image and record its identity; a deliberately pinned reproduction should retain its selected image. The quick-start pull above targets native x86_64; use --platform from uname2platform.sh for other targets. A pull can replace the cached tag; current registry contents are not established by this skill.

Output artifacts

Job 99-copy-archives.sh writes to artifacts/ (gitignored, host-side, owned by your user):

artifacts/
├── netdata-x86_64-latest.gz.run            # copied alias of the versioned archive
├── netdata-x86_64-v2.10.0-171-nightly.gz.run
├── netdata-latest.gz.run                   # x86_64 only — generic alias
├── netdata-v2.10.0-171-nightly.gz.run      # x86_64 only — generic alias
└── cache/                                  # build cache, see below

For non-x86_64 builds, only the two netdata-<arch>-* files are produced (packaging/makeself/jobs/99-copy-archives.sh:25-30).

Verify a build:

ls -la artifacts/
sha256sum artifacts/netdata-x86_64-latest.gz.run

# What's inside (read-only inspection, does not run the installer)
sh artifacts/netdata-x86_64-latest.gz.run --info
sh artifacts/netdata-x86_64-latest.gz.run --list | head

Each .gz.run is a makeself archive: a shell prefix that extracts the gzipped tar embedded after it. Run it as root on the target to install.

Build cache

artifacts/cache/<arch>/ holds the compiled third-party deps (openssl, curl, bash, libunwind, libnetfilter_acct, ioping) keyed by their pinned source versions in packaging/makeself/bundled-packages.version. The fetch logic is in packaging/makeself/functions.sh (cache_path(), fetch(), fetch_git(), store_cache()).

Implications:

• First build: ~22-25 min on a 24-core host (most time = third-party compile + Rust crate compile + LTO link of the C plugins).
• Cache hit: ~10-15 min (skips the third-party deps; only the netdata sources rebuild).
• The cache survives git checkout and git clean -fd (it's under the gitignored artifacts/).
• Bumping a version in bundled-packages.version invalidates that one entry — the rest still reuse.
• Cache entries are version-derived directories under <arch>/<package>/; image contents and compiler flags are not part of that key. For a cold rebuild, preserve the exact cache being invalidated outside the active cache path, or build in an isolated checkout. Do not delete all of artifacts/: it also holds installers and other architectures. Any deletion still needs the existing task authorization.