Building Reproducible Docker Dev Environments for Embedded Linux (RK3588, RV1126, RK3568)

Building Reproducible Docker Dev Environments for Embedded Linux

The Problem

If you’re working with embedded Linux boards — RK3588, RK3588S, RV1126, RK3568, or similar Rockchip SoCs — you know the pain:

• Every developer on the team has a slightly different toolchain version installed
• Build results differ between machines (“it works on my Docker container”)
• Supporting Ubuntu 20.04, 22.04, and 24.04 simultaneously without breaking any of them
• Ports collide when you run containers for multiple chip families at the same time
• Pushing images to a private Harbor registry requires glue scripts nobody documents

The standard answer is “containerise your dev environment” — but the container definitions themselves become a maintenance burden. You end up with 5 Dockerfiles that diverge over time.

The Solution: HarborPilot

HarborPilot is a fully scripted toolchain that automates the entire build-tag-push lifecycle for embedded Linux Docker dev environments.

The key ideas:

1. One Monolithic 5-Stage Dockerfile

Instead of 5 separate Dockerfiles, there’s one:

Stage 1: base OS setup (apt sources, packages, user creation, locale)
Stage 2: dev tools (cmake, gdb, CUDA, OpenCV, Node.js, Python)
Stage 3: SDK initialisation (git init, symlinks, helper scripts)
Stage 4: environment config (proxy, profile.d variables)
Stage 5: workspace + entrypoint + tests

Platform-specific behaviour is controlled by ARG/ENV variables injected at build time — not by different Dockerfiles.

2. Three-Layer Config Inheritance

Layer 1:  configs/defaults/*.env        ← global defaults (10 domain-scoped files)
Layer 2:  configs/platform-independent/common.env  ← project version & constants
Layer 3:  configs/platforms/<name>.env  ← per-platform overrides only (≤20 lines)

A new platform file looks like this (real example for RK3568 Ubuntu 20.04):

# configs/platforms/rk3568-rk3568_ubuntu-20.04.env
PRODUCT_NAME="rk3568-rk3568_ubuntu-20-04"
CHIP_FAMILY="rk3568"
CHIP_EXTRACT_NAME="rk3568"
OS_VERSION="20.04"
OS_VERSION_ID="20-04"
PORT_SLOT=2
HOST_VOLUME_DIR="/mnt/disk/volumes/rk3568-rk3568_ubuntu-20.04"
HAS_PROXY=true
HTTP_PROXY_IP="192.168.3.152"
HTTPS_PROXY_IP="192.168.3.152"
HAVE_GITLAB_SERVER=TRUE
GITLAB_SERVER_IP="192.168.3.67"

That’s the entire file. Everything else inherits from the defaults.

3. PORT_SLOT: Zero Port Conflicts

Running containers for RK3588 and RK3568 simultaneously? Set different PORT_SLOT values:

PORT_SLOT=0 → SSH: 2109, GDB: 2345
PORT_SLOT=1 → SSH: 2119, GDB: 2355
PORT_SLOT=2 → SSH: 2129, GDB: 2365
...

One integer drives all port mappings. No manual management, no collisions.

Ubuntu 24.04 Support: Three Specific Fixes

Ubuntu 24.04 breaks things that work fine on 20.04 and 22.04. HarborPilot handles them:

Fix 1: DEB822 apt format

Ubuntu 24.04 dropped the legacy /etc/apt/sources.list format. The China mirror replacement script detects the OS version and generates the correct format automatically:

if [ "${OS_VERSION}" = "24.04" ]; then
    # Write DEB822 format to /etc/apt/sources.list.d/ubuntu.sources
else
    # Write legacy format to /etc/apt/sources.list
fi

Fix 2: UID 1000 pre-occupied

On Ubuntu 24.04, UID 1000 is already taken by the default ubuntu user. setup_base.sh detects this and reassigns the existing UID before creating the dev user.

Fix 3: pip PEP 668

Ubuntu 24.04 enforces PEP 668 (externally managed Python). pip installs now require:

pip3 install --break-system-packages <package>

This is handled automatically via OS_VERSION conditionals in install_dev_tools.sh.

One Command to Build, One Command to Run

Build:

./harbor
# Interactive platform selection → build → tag → push → verify manifest digest

Run on any Ubuntu host:

./project_handover/clientside/ubuntu/ubuntu_only_entrance.sh start

Create a new platform (non-interactive, CI-friendly):

./scripts/create_platform.sh --non-interactive \
    --name rk3566-debian12 --os debian --os-version 12 \
    --harbor-ip 192.168.3.68 --port-slot 6

Supported Platforms

AI Agent Support

The .env config files are the intent layer — they’re plain text, human-readable, and can be read and modified by AI coding agents directly. The docs/en/1-for-ai/ directory contains a full codebase map and working rules for AI agents.

GitHub

→ github.com/potterwhite/HarborPilot

MIT License. Contributions welcome.

• ←Previous
• Next→