# Handling Architecture-Specific Builds (x86_64 vs ARM64) with LabNow AI

> Learn how LabNow AI handles architecture specific builds for x86_64 and ARM64. It automatically detects your CPU, translates identifiers, and downloads correct binaries for seamless integration.

- Repository: [LabNow.ai/lab-foundation](https://github.com/labnow-ai/lab-foundation)
- Tags: how-to-guide
- Published: 2026-03-05

---

**LabNow AI automatically detects host CPU architecture using `uname -m`, translates kernel identifiers to Debian-compatible naming conventions (amd64/arm64), and dynamically constructs download URLs to install the correct x86_64 or ARM64 binaries across its lab-foundation repository.**

The lab-foundation repository provides infrastructure automation scripts that must execute reliably on both Intel/AMD (x86_64) and ARM (aarch64) hardware. Handling architecture-specific builds requires a consistent strategy for detecting the host platform, normalizing naming conventions, and validating compatibility before fetching pre-compiled binaries. The project solves this through reusable Bash helper scripts that eliminate the need for separate Dockerfiles per architecture.

## The Five-Step Architecture Detection Pattern

LabNow AI implements a standardized workflow across all setup scripts to ensure cross-platform compatibility:

- **Detect raw architecture:** Query the kernel using `uname -m` to obtain values like `x86_64`, `aarch64`, or `armv7l`.
- **Translate naming conventions:** Map kernel outputs to Debian/Ubuntu package archive names using `sed` substitutions (x86_64→amd64, aarch64→arm64).
- **Validate support:** Check against an allowed list of architectures to prevent silent failures on unsupported CPUs.
- **Construct dynamic URLs:** Embed the normalized `$ARCH` variable into download URLs for tools like Docker Compose, Image-Syncer, and YQ.
- **Install system-wide:** Download, `chmod +x`, and move binaries to `/usr/bin` or `/opt/bin` with version verification.

### Normalizing Kernel Architecture Names

The core translation logic appears in multiple files, including [`docker_docker_kit/work/script-setup-docker.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_docker_kit/work/script-setup-docker.sh) at line 16 and [`docker_atom/work/script-setup-sys.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-setup-sys.sh) at line 5. The scripts use `sed` to convert `uname -m` outputs into package-manager-friendly strings:

```bash
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/' -e 's/armv7l/arm/')

```

This single line ensures that x86_64 hosts identify as `amd64`, aarch64 hosts as `arm64`, and armv7l hosts as `arm`, matching the naming conventions used by Debian, Ubuntu, and many upstream binary releases.

### Validating Supported Platforms

Before attempting downloads, the scripts guard against unsupported architectures. In [`docker_atom/work/script-setup.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-setup.sh) at lines 10-11, the code validates the translated `$ARCH` variable against a regex pattern:

```bash
[[ "$ARCH" =~ ^(amd64|arm64|arm)$ ]] || { echo "Unsupported architecture: $(uname -m)"; exit 1; }

```

This prevents execution on exotic or incompatible hardware and provides immediate feedback to operators.

## Dynamic Binary Installation Implementation

### Docker Compose and Image-Syncer Setup

The [`docker_docker_kit/work/script-setup-docker.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_docker_kit/work/script-setup-docker.sh) script demonstrates dynamic URL construction for both Docker Compose and Image-Syncer. At lines 7-9, it builds the Docker Compose download URL using the normalized architecture variable:

```bash
VER_COMPOSE=$(curl -sL https://github.com/docker/compose/releases.atom | grep 'releases/tag' | head -1 | grep -Po '\d[.\d]+')
URL_COMPOSE="https://github.com/docker/compose/releases/download/v${VER_COMPOSE}/docker-compose-linux-${ARCH}"
sudo curl -o /usr/bin/docker-compose -sL ${URL_COMPOSE}
sudo chmod +x /usr/bin/docker-compose

```

Similarly, for Image-Syncer at lines 15-19, the script constructs:

```bash
URL_SYNCER="https://github.com/AliyunContainerService/image-syncer/releases/download/v${VER_SYNCER}/image-syncer-v${VER_SYNCER}-linux-${ARCH}.tar.gz"

```

### YQ Binary Management

The [`docker_atom/work/script-setup.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-setup.sh) file handles YQ installation with explicit architecture validation at lines 8-11, followed by dynamic URL construction at lines 12-14:

```bash
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/' -e 's/armv7l/arm/')
[[ "$ARCH" =~ ^(amd64|arm64|arm)$ ]] || { echo "Unsupported architecture for yq: $(uname -m)"; exit 1; }

VER_YQ=$(curl -sL -o /dev/null -w "%{url_effective}" https://github.com/mikefarah/yq/releases/latest | grep -oP 'v\K[\d.]+')
URL_YQ="https://github.com/mikefarah/yq/releases/download/v${VER_YQ}/yq_linux_${ARCH}"
curl -fSL "${URL_YQ}" -o /tmp/yq
install -m 0755 -D /tmp/yq /opt/bin/yq
ln -sf /opt/bin/yq /usr/bin/yq

```

### PostgreSQL Extension Mirroring

For APT-based installations, [`docker_db_postgres/rootfs/opt/utils/script-setup-pg-ext-mirror.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_db_postgres/rootfs/opt/utils/script-setup-pg-ext-mirror.sh) at lines 19-23 uses the same architecture mapping to configure pgxman repositories:

```bash
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
curl -fsSL https://apt.pgxman.com/pgxman-keyring.gpg | gpg --dearmor | sudo tee ${APT_KEYRING_DIR}/pgxman-cli.gpg > /dev/null
echo "deb [arch=${ARCH} signed-by=${APT_KEYRING_DIR}/pgxman-cli.gpg] https://apt.pgxman.com/cli stable main" \
  | sudo tee ${APT_SOURCE_DIR}/pgxman-cli.list >/dev/null

```

## Summary

- **LabNow AI** handles architecture-specific builds by detecting the host CPU with `uname -m` and normalizing output via `sed` translation in [`docker_atom/work/script-setup-sys.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-setup-sys.sh).
- The repository supports **amd64** (x86_64), **arm64** (aarch64), and **arm** (armv7l) architectures through regex validation in [`docker_atom/work/script-setup.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-setup.sh).
- **Dynamic URL construction** ensures correct binaries for Docker Compose, Image-Syncer, and YQ without maintaining separate per-architecture scripts.
- The pattern is consistently implemented across `docker_docker_kit`, `docker_atom`, and `docker_db_postgres` components, enabling seamless multi-platform deployments.

## Frequently Asked Questions

### How does LabNow AI detect the host CPU architecture?

The scripts query the kernel using `uname -m`, which returns raw identifiers like `x86_64` or `aarch64`. This output is piped through `sed` to translate values into Debian-compatible naming conventions (amd64, arm64, arm) as implemented in [`docker_docker_kit/work/script-setup-docker.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_docker_kit/work/script-setup-docker.sh).

### Why does LabNow AI map x86_64 to amd64 instead of using the raw output?

Debian, Ubuntu, and many upstream release assets (including Docker Compose and YQ) use the `amd64` and `arm64` nomenclature rather than kernel identifiers. Translating early prevents URL mismatches and ensures compatibility with standard package repositories.

### What happens if the architecture is unsupported?

The scripts validate the normalized `$ARCH` variable against a regex pattern `^(amd64|arm64|arm)$` in files like [`docker_atom/work/script-setup.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-setup.sh). If the check fails, the script prints an error message and exits immediately, preventing attempts to download incompatible binaries.

### Can I use these LabNow AI scripts on non-Debian systems?

While the architecture detection logic (`uname -m` and `sed` translation) works on any Linux distribution, the URL construction and installation paths target Debian/Ubuntu conventions (amd64/arm64 naming, `/usr/bin` locations). Adaptation would be required for RHEL-based systems using x86_64/aarch64 nomenclature.