{"id":47610562,"url":"https://github.com/potterwhite/HarborPilot","last_synced_at":"2026-04-04T03:00:53.338Z","repository":{"id":327377670,"uuid":"1109050365","full_name":"potterwhite/HarborPilot","owner":"potterwhite","description":"This is a One-Click docker images and containers setup base which is doing via a lot of bash scripts. My primary target is embedded linux development and you can choose your target whatever you want. Have fun. Thank you for your starts.","archived":false,"fork":false,"pushed_at":"2026-03-30T03:24:52.000Z","size":3405,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T02:21:53.914Z","etag":null,"topics":["arm","cross-platform","devcontainer","docker","embedded-linux","rk3568","rk3588","rv1126","toolchain"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/potterwhite.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-03T09:15:35.000Z","updated_at":"2026-03-30T03:24:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/potterwhite/HarborPilot","commit_stats":null,"previous_names":["potterwhite/harborpilot"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/potterwhite/HarborPilot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potterwhite%2FHarborPilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potterwhite%2FHarborPilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potterwhite%2FHarborPilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potterwhite%2FHarborPilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/potterwhite","download_url":"https://codeload.github.com/potterwhite/HarborPilot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potterwhite%2FHarborPilot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31385935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T01:22:39.193Z","status":"online","status_checked_at":"2026-04-04T02:00:07.569Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arm","cross-platform","devcontainer","docker","embedded-linux","rk3568","rk3588","rv1126","toolchain"],"created_at":"2026-04-01T20:00:59.472Z","updated_at":"2026-04-04T03:00:53.333Z","avatar_url":"https://github.com/potterwhite.png","language":"Shell","funding_links":[],"categories":["Developer Workflow"],"sub_categories":["Development Environment"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eHarborPilot\u003c/h1\u003e\n  \u003cp\u003e\u003ci\u003eOne-Command Docker Development Environment for Embedded Linux — Multi-Platform, Reproducible, Registry-Backed\u003c/i\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/en/assets/dark-background.png\" alt=\"HarborPilot Banner\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/potterwhite/HarborPilot/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/potterwhite/HarborPilot?color=blue\u0026label=version\"\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" alt=\"License\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/host-Ubuntu-orange?style=flat-square\" alt=\"Host Platform\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Docker-required-2496ED?style=flat-square\u0026logo=docker\u0026logoColor=white\" alt=\"Docker\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/shell-bash-4EAA25?style=flat-square\u0026logo=gnubash\u0026logoColor=white\" alt=\"Shell\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/target-Rockchip%20%7C%20ARM%20SoC-lightgrey?style=flat-square\" alt=\"Target\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eEnglish\u003c/strong\u003e | \u003ca href=\"docs/zh/readme.md\"\u003e简体中文\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What problem does HarborPilot solve?\n\n**Are you building Docker development environments for embedded Linux boards?**\nBoards like RK3588, RK3588S, RK3568, RV1126 — or any ARM-based SoC running Ubuntu or Debian?\n\nThe typical pain points:\n- Every developer has a slightly different toolchain installed → builds fail on different machines\n- Supporting multiple chip families means maintaining multiple diverging Dockerfiles\n- Adding Ubuntu 24.04 support breaks what worked on 20.04 (apt format, UID collisions, pip PEP 668)\n- Port collisions when running containers for multiple platforms simultaneously\n- Pushing images to a private Harbor registry requires glue scripts nobody documents\n\n**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.\n\n---\n\n## What is HarborPilot?\n\nHarborPilot is a fully scripted toolchain for building, managing, and distributing\n**containerised cross-compilation development environments** for embedded Linux targets.\n\n- **One command to build** — `./harbor` selects a platform, builds a 5-stage Docker image, tags it, and pushes it to your private Harbor registry\n- **One command to run** — `ubuntu_only_entrance.sh start` brings up a fully-configured container on any Ubuntu host in seconds\n- **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\n- **PORT_SLOT-based port allocation** — a single integer derives SSH and GDB ports automatically, eliminating manual port management\n\nPrimary targets: Rockchip SoCs (RK3588S, RK3568, RV1126, RV1126bp) on Ubuntu 20.04 / 22.04 / 24.04.\nArchitecture is platform-agnostic — adding a Debian platform or a different chip family takes minutes.\n\n---\n\n## Key Features\n\n| Feature | Details |\n|---|---|\n| **One command to build** | `./harbor` — select platform → build → tag → push → verify manifest |\n| **One command to run** | `ubuntu_only_entrance.sh start` — fully configured container in seconds |\n| **New platform in 20 lines** | Three-layer config: `defaults/` → `common.env` → `platform.env` · only overrides needed |\n| **Zero port conflicts** | `PORT_SLOT` formula — SSH and GDB ports derived automatically, never collide |\n| **Registry lifecycle** | Auto push + manifest digest verification — not just \"hope it uploaded\" |\n| **Chip-family grouping** | `CHIP_FAMILY` drives Harbor project, SDK repo, SSH keys — RK3588 variants share one team |\n| **AI-operable config** | `.env` files are the intent layer — AI agents can read, modify, then call `./harbor` |\n| **Embedded-first defaults** | GDB server, serial passthrough, OpenCV, optional CUDA — all pre-wired |\n| **Cross-distro support** | Ubuntu 20.04 / 22.04 / 24.04 handled correctly (DEB822, UID 1000, PEP 668) |\n| **envsubst templates** | All stage configuration rendered via `envsubst` — no fragile sed pipelines |\n\n---\n\n## How does the three-layer config work?\n\n```\nLayer 1:  configs/defaults/*.env        ← Global defaults (OS, tools, ports, registry…)\nLayer 2:  configs/platform-independent/common.env  ← Project version \u0026 constants\nLayer 3:  configs/platforms/\u003cname\u003e.env  ← Per-platform overrides only (≤20 lines)\n```\n\nLast layer wins. A new platform file only contains what **differs** from the defaults — typically:\n`PRODUCT_NAME`, `OS_VERSION`, `PORT_SLOT`, `HOST_VOLUME_DIR`, and any chip-specific overrides.\n\n**PORT_SLOT** is the single source of port truth:\n- `CLIENT_SSH_PORT = 2109 + PORT_SLOT × 10`\n- `GDB_PORT = 2345 + PORT_SLOT × 10`\n\nAdd a new platform with `./scripts/create_platform.sh` (interactive) or `--non-interactive` for CI.\n\n→ Deep dive: [docs/en/3-highlights/config_layers.md](docs/en/3-highlights/config_layers.md)\n\n---\n\n## Repository Structure\n\n```\nHarborPilot/\n│\n├── harbor                            ← Entry point: build → tag → push → verify\n│\n├── configs/\n│   ├── defaults/                     ← Layer 1 · 10 domain-scoped default files\n│   │   ├── 01_base.env               OS, user, timezone, locale\n│   │   ├── 02_build.env              Docker BuildKit settings\n│   │   ├── 03_tools.env              Dev tool switches \u0026 versions (CUDA, OpenCV, Node…)\n│   │   ├── 04_workspace.env          Workspace paths \u0026 build settings\n│   │   ├── 05_registry.env           Harbor / GitLab server address\n│   │   ├── 06_sdk.env                SDK install switch\n│   │   ├── 07_volumes.env            Volume root path\n│   │   ├── 08_samba.env              Samba credentials\n│   │   ├── 09_runtime.env            SSH / GDB / NVIDIA / serial switches\n│   │   └── 11_proxy.env              HTTP/HTTPS proxy (off by default)\n│   ├── platform-independent/\n│   │   └── common.env                ← Layer 2 · project version \u0026 constants\n│   └── platforms/\n│       ├── rk3588-rk3588s_ubuntu-22.04.env   ← Layer 3 · platform overrides only\n│       ├── rk3588-rk3588s_ubuntu-24.04.env\n│       ├── rk3568-rk3568_ubuntu-20.04.env\n│       ├── rk3568-rk3568_ubuntu-22.04.env\n│       ├── rv1126-rv1126_ubuntu-22.04.env\n│       └── rv1126-rv1126bp_ubuntu-22.04.env\n│\n├── docker/\n│   └── dev-env-clientside/           ← 5-stage Dockerfile\n│       ├── Dockerfile                   base → tools → sdk → config → final\n│       └── build.sh\n│\n├── scripts/\n│   ├── create_platform.sh            ← Platform wizard (interactive + non-interactive)\n│   └── port_calc.sh                  ← PORT_SLOT → SSH/GDB port calculation\n│\n├── project_handover/\n│   └── clientside/ubuntu/\n│       ├── ubuntu_only_entrance.sh   ← Container lifecycle manager\n│       └── harbor.crt                ← Harbor CA cert (install once per host)\n│\n└── docs/                             ← Bilingual documentation (EN + ZH)\n    ├── en/\n    │   ├── 1-for-ai/                 AI agent reference files\n    │   ├── 2-progress/               Phase tracking \u0026 roadmap\n    │   ├── 3-highlights/             Architecture decisions \u0026 analysis\n    │   └── 4-for-beginner/           Quick start guide\n    └── zh/                           Chinese mirror of docs/en/\n```\n\n---\n\n## Supported Platforms\n\n| Platform | Ubuntu | SSH Port | GDB Port | Notes |\n|---|---|---|---|---|\n| `rk3588-rk3588s_ubuntu-22.04` | 22.04 | 2109 | 2345 | NVIDIA GPU supported |\n| `rv1126-rv1126bp_ubuntu-22.04` | 22.04 | 2119 | 2355 | |\n| `rk3568-rk3568_ubuntu-20.04` | 20.04 | 2129 | 2365 | |\n| `rv1126-rv1126_ubuntu-22.04` | 22.04 | 2139 | 2375 | |\n| `rk3568-rk3568_ubuntu-22.04` | 22.04 | 2149 | 2385 | |\n| `rk3588-rk3588s_ubuntu-24.04` | 24.04 | 2159 | 2395 | Without NVIDIA GPU |\n\n---\n\n## Quick Start\n\n→ **Full guide: [docs/en/4-for-beginner/quick_start.md](docs/en/4-for-beginner/quick_start.md)**\n\n```bash\n# 1. Install Docker and trust the Harbor CA cert  (once per host)\n#    → see docs/en/4-for-beginner/quick_start.md\n\n# 2. Log in to your Harbor registry\ndocker login \u003cregistry-ip\u003e:\u003cregistry-port\u003e\n\n# 3. Build — pick your target platform interactively\n./harbor\n\n# 4. Start your development container\n./project_handover/clientside/ubuntu/ubuntu_only_entrance.sh start\n```\n\n**Non-interactive (CI / scripted):**\n```bash\n./scripts/create_platform.sh --non-interactive \\\n    --name rk3566-debian12 --os debian --os-version 12 \\\n    --harbor-ip 192.168.3.68 --port-slot 6\n```\n\n---\n\n## FAQ\n\n**Q: Can I use this for a chip family not listed above?**\nA: 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.\n\n**Q: Does it work with Ubuntu 24.04?**\nA: Yes. HarborPilot handles Ubuntu 24.04's DEB822 apt format, pre-occupied UID 1000, and pip's externally-managed-environment restriction automatically.\n\n**Q: Can I use it without a Harbor registry?**\nA: Yes. Set `HAVE_HARBOR_SERVER=FALSE` in your platform config and images stay local.\n\n**Q: Is the Dockerfile AI-readable?**\nA: 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.\n\n---\n\n## Deprecation Notices\n\n| Component | Status |\n|---|---|\n| Windows host | ❌ **Dropped** — Ubuntu host only. |\n\n---\n\n## License\n\n[MIT](LICENSE) © 2024 PotterWhite\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpotterwhite%2FHarborPilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpotterwhite%2FHarborPilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpotterwhite%2FHarborPilot/lists"}