임베디드 SoC 개발팀이 5개의 분산된 Dockerfile을 단일 5단계 Monolithic 구조로 통합하고 PORT_SLOT 기반 자동 포트 관리로 다중 플랫폼 동시 실행 시 포트 충돌 제거

Context

임베디드 Linux 보드(RK3588, RV1126, RK3568 등) 개발 시 플랫폼별 5개의 Dockerfile이 시간 경과에 따라 서로 다르게 변경되는 문제가 발생했다. 동일 플랫폼의 컨테이너를 동시 실행할 때 SSH, GDB 등의 포트가 충돌하며, Ubuntu 버전 업그레이드(20.04 → 24.04)마다 apt 미러, pip 설치, UID 할당이 모두 깨지는 상황이 반복되었다.

Technical Solution

• Dockerfile을 5단계 구조로 통합: base OS → dev tools → SDK init → env config → workspace+entrypoint로 단계별 역할 분리하고 ARG/ENV를 통해 플랫폼별 동작 주입
• PORT_SLOT 정수값으로 모든 포트 매핑 자동화: CLIENT_SSH_PORT = 2109 + PORT_SLOT × 10, GDB_PORT = 2345 + PORT_SLOT × 10 규칙으로 포트 충돌 자동 회피
• 3계층 설정 상속 시스템 도입: configs/defaults/.env(전역 기본값 10개 파일) → configs/common.env(프로젝트 상수) → configs/platforms/.env(플랫폼별 오버라이드 ≤20줄)
• Ubuntu 버전별 조건부 처리: OS_VERSION 조건문으로 DEB822 apt 포맷, UID 1000 충돌, PEP 668 pip 제약 등 3가지 Breaking Change 동시 지원
• 단일 ./harbor 명령어로 빌드·태깅·Harbor 푸시·매니페스트 검증을 순차 자동 실행
• envsubst를 sed 대신 사용: 템플릿 렌더링 시 escaping 오류 제거
• ubuntu_only_entrance.sh를 400줄 단일 파일에서 6개 모듈로 분할 리팩토링

Impact

새로운 플랫폼 추가 시 설정 파일 15~20줄만 작성 필요 (기존: 전체 Dockerfile 작성).

Key Takeaway

다중 플랫폼 컨테이너 환경에서는 플랫폼별 전체 매니페스트 복제보다 설정 상속 계층과 ARG/ENV 기반 조건부 로직으로 단일 소스를 유지하는 것이 drift 방지와 유지보수성을 동시에 달성한다.