README.md

June 25, 2026 · View on GitHub

HarborPilot

One-Command Docker Development Environment for Embedded Linux — Multi-Platform, Reproducible, Registry-Backed

HarborPilot Banner

What problem does HarborPilot solve?

Are you building Docker development environments for embedded Linux boards? Boards like RK3588, RK3588S, RK3568, RV1126 — or any ARM-based SoC running Ubuntu or Debian?

The typical pain points:

Every developer has a slightly different toolchain installed → builds fail on different machines
Supporting multiple chip families means maintaining multiple diverging Dockerfiles
Adding Ubuntu 24.04 support breaks what worked on 20.04 (apt format, UID collisions, pip PEP 668)
Port collisions when running containers for multiple platforms simultaneously
Pushing images to a private Harbor registry requires glue scripts nobody documents

HarborPilot solves all of this with a single-command build pipeline, a three-layer configuration system that lets new platforms inherit all defaults in under 20 lines, and automatic port allocation that guarantees zero collisions.

What is HarborPilot?

HarborPilot is a fully scripted toolchain for building, managing, and distributing containerised cross-compilation development environments for embedded Linux targets.

One command to build — ./harbor selects a platform, builds a 5-stage Docker image, tags it, and pushes it to your private Harbor registry
One command to run — ubuntu_only_entrance.sh start brings up a fully-configured container on any Ubuntu host in seconds
A three-layer config system — change one global default and every platform inherits it automatically; a new platform needs fewer than 20 lines of config
PORT_SLOT-based port allocation — a single integer derives SSH and GDB ports automatically, eliminating manual port management

Primary targets: Rockchip SoCs (RK3588S, RK3568, RV1126, RV1126bp) on Ubuntu 20.04 / 22.04 / 24.04. Architecture is platform-agnostic — adding a Debian platform or a different chip family takes minutes.

Key Features

Feature	Details
One command to build	`./harbor` — select host → build → tag → push → verify manifest
One command to run	`ubuntu_only_entrance.sh start` — fully configured container in seconds
Host-primary architecture	Host config is the user object; platform/defaults are invisible support layers
Zero port conflicts	`PORT_SLOT` formula — SSH and GDB ports derived automatically, never collide
Registry lifecycle	Auto push + manifest digest verification — not just "hope it uploaded"
Chip-family grouping	`CHIP_FAMILY` drives Harbor project, SDK repo, SSH keys — RK3588 variants share one team
AI-operable config	`.env` files are the intent layer — AI agents can read, modify, then call `./harbor`
Embedded-first defaults	GDB server, serial passthrough, OpenCV, optional CUDA — all pre-wired
Cross-distro support	Ubuntu 20.04 / 22.04 / 24.04 handled correctly (DEB822, UID 1000, PEP 668)
envsubst templates	All stage configuration rendered via `envsubst` — no fragile sed pipelines

How does the three-layer config work?

Layer 1:  configs/1_defaults/*.env        ← Global defaults (automatic, invisible)
Layer 2:  configs/2_platforms/<name>.env  ← Platform identity (automatic, invisible)
Layer 3:  configs/3_hosts/<hostname>.env   ← Host config (THE user-facing object)

Host is the primary object. Each host config declares its platform via BASE_PLATFORM and contains all machine-specific overrides. Users only interact with host configs — the platform and defaults layers are internal support layers.

A host config needs at minimum:

BASE_PLATFORM — which platform to use (e.g., rk3588-rk3588s_ubuntu-24.04)
HOST_VOLUME_DIR — where to store Docker volumes on this machine

PORT_SLOT is the single source of port truth:

CLIENT_SSH_PORT = 2109 + PORT_SLOT × 10
GDB_PORT = 2345 + PORT_SLOT × 10

Add a new host with ./harbor → "Create new host config", or manually copy TEMPLATE.env.example.

→ Deep dive: docs/en/3-highlights/config_layers.md

Repository Structure

HarborPilot/
│
├── harbor                            ← Entry point: build → tag → push → verify
│
├── configs/
│   ├── 1_defaults/                   ← Layer 1 · 6 stage-aligned default files
│   │   ├── 00_global.env             Project version, metadata, SDK versions
│   │   ├── 01_stage_1st_base.env     OS, user, timezone, locale
│   │   ├── 02_stage_2nd_build.env    BuildKit, dev tools, CUDA, OpenCV
│   │   ├── 03_stage_3rd_sdk.env      Registry addresses + SDK switch & paths
│   │   ├── 04_stage_4th_proxy.env    HTTP/HTTPS proxy (off by default)
│   │   └── 05_stage_5th_runtime.env  Workspace, volumes, Samba, SSH/GDB/NVIDIA
│   ├── platforms/                    ← Layer 2 · per-platform overrides only
│   │   ├── rk3588-rk3588s_ubuntu-22.04.env
│   │   ├── rk3588-rk3588s_ubuntu-24.04.env
│   │   ├── rk3568-rk3568_ubuntu-20.04.env
│   │   ├── rk3568-rk3568_ubuntu-22.04.env
│   │   ├── rv1126-rv1126_ubuntu-22.04.env
│   │   └── rv1126-rv1126bp_ubuntu-22.04.env
│   └── hosts/                        ← Layer 3 · host configs (THE user-facing object)
│
├── docker/
│   └── dev-env-clientside/           ← 5-stage Dockerfile
│       ├── Dockerfile                   base → tools → sdk → config → final
│       └── build.sh
│
├── scripts/
│   ├── create_platform.sh            ← Platform wizard (interactive + non-interactive)
│   └── port_calc.sh                  ← PORT_SLOT → SSH/GDB port calculation
│
├── project_handover/
│   └── clientside/ubuntu/
│       ├── ubuntu_only_entrance.sh   ← Container lifecycle manager
│       └── harbor.crt                ← Harbor CA cert (install once per host)
│
└── docs/                             ← Bilingual documentation (EN + ZH)
    ├── en/
    │   ├── 1-for-ai/                 AI agent reference files
    │   ├── 2-progress/               Phase tracking & roadmap
    │   ├── 3-highlights/             Architecture decisions & analysis
    │   └── 4-for-beginner/           Quick start guide
    └── zh/                           Chinese mirror of docs/en/

Supported Platforms

Platform	Ubuntu	SSH Port	GDB Port	Notes
`rk3588-rk3588s_ubuntu-22.04`	22.04	2109	2345	NVIDIA GPU supported
`rv1126-rv1126bp_ubuntu-22.04`	22.04	2119	2355
`rk3568-rk3568_ubuntu-20.04`	20.04	2129	2365
`rv1126-rv1126_ubuntu-22.04`	22.04	2139	2375
`rk3568-rk3568_ubuntu-22.04`	22.04	2149	2385
`rk3588-rk3588s_ubuntu-24.04`	24.04	2159	2395	Without NVIDIA GPU

Quick Start

→ Full guide: docs/en/4-for-beginner/quick_start.md

# 1. Install Docker and trust the Harbor CA cert  (once per host)
#    → see docs/en/4-for-beginner/quick_start.md

# 2. Log in to your Harbor registry
docker login <registry-ip>:<registry-port>

# 3. Build — pick your target platform interactively
./harbor

# 4. Start your development container
./project_handover/clientside/ubuntu/ubuntu_only_entrance.sh start

Non-interactive (CI / scripted):

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

FAQ

Q: Can I use this for a chip family not listed above? A: Yes. Run ./scripts/create_platform.sh to add a new platform in minutes. The wizard auto-assigns a PORT_SLOT to avoid conflicts and generates the config file with all required fields.

Q: Does it work with Ubuntu 24.04? A: Yes. HarborPilot handles Ubuntu 24.04's DEB822 apt format, pre-occupied UID 1000, and pip's externally-managed-environment restriction automatically.

Q: Can I use it without a Harbor registry? A: Yes. Set HAVE_HARBOR_SERVER=FALSE in your platform config and images stay local.

Q: Is the Dockerfile AI-readable? A: The .env config files are the intent layer — AI agents can read and modify them directly, then invoke ./harbor to build. The docs/en/1-for-ai/ directory contains a full codebase map and working rules specifically for AI agents.

Deprecation Notices

Component	Status
Windows host	❌ Dropped — Ubuntu host only.