Harbor ARM64(arm64) 이미지 소스 빌드 기록

Harbor는 ARM(arm64)에서 공식 이미지/공식 설치 흐름이 그대로 맞지 않는 구간이 있어서, ARM 환경에서는 에뮬레이터를 돌리거나 소스 기반으로 arm64 이미지를 직접 빌드하는 방식이 필요했다.

사실 누군가 이미 빌드하고 이미지를 제공하는 사람이 많을 줄 알았는데, 생각보다 정보가 너무 적어서 놀랐다. 그래도 일단 직접 빌드하기로 마음 먹었기 때문에 죽이되든 밥이되든 해봐야겠다고 생각했다.

먼저 소스 코드는 아래 레포지토리에서 다운 받았다.
소스코드 레포지터리

그러나 빌드 과정이 조금 쉽지 않았는데, 다시 한 번 복기하며 이해하고자 또 나와 같은 사람들이 이런 행위를 겪지 않았으면 해서 해당 포스팅을 작성하기로 마음 먹었다.

빌드 과정은 크게 세 파트로 나뉜다.

1. 빌드 환경 준비
2. harbor-arm 소스 코드 준비
3. arm64 이미지 빌드

1. 빌드 환경 준비

1-1. Docker/Buildx 확인

Harbor 이미지를 arm64로 빌드하려면 buildx가 arm64 플랫폼을 처리할 수 있어야 한다.

docker version
docker buildx version
docker buildx ls

1-2. 빌드에 필요한 패키지 설치(Rocky Linux 기준)

dnf install -y \
  git make gcc gcc-c++ \
  tar gzip xz bzip2 \
  curl jq patch rsync findutils \
  openssl openssl-devel

아래는 이 도구들이 어떤 기능을 하는지 간단하게 정리해두었다.

• git: 소스 코드(레포지토리) 내려받기/버전 관리.
• make: Harbor 빌드에 정의된 Makefile 타겟 실행(compile, build 등).
• gcc, gcc-c++: C/C++ 기반 의존성/바이너리 컴파일(일부 라이브러리/툴 빌드 시 필요).
• tar: 소스/아카이브(tarball) 압축 파일 풀기/묶기.
• gzip, xz, bzip2: .tar.gz, .tar.xz, .tar.bz2 같은 압축 포맷 해제/생성에 필요.
• curl: 외부 리소스(의존 파일, 바이너리, 스크립트 등) 다운로드/HTTP 요청 테스트.
• jq: JSON 파싱/필터링(예: Harbor API 응답에서 버전 추출 같은 작업).
• patch: 소스 코드에 패치 파일 적용(버그 수정/수정사항 반영할 때).
• rsync: 대용량 파일/디렉토리 동기화(빌드 산출물 복사/동기화에 유리).
• findutils: find, xargs 같은 파일 탐색/일괄 처리(빌드 산출물 찾기/정리할 때 자주 씀).
• openssl: 인증서/키 생성·검증, TLS 관련 테스트(예: x509, s_client).
• openssl-devel: OpenSSL 개발 헤더/라이브러리(빌드 중 OpenSSL 연동이 필요한 컴파일 단계에서 요구될 수 있음).

2. harbor-arm 소스 코드 준비

레포지토리를 클론한 뒤 빌드 작업 디렉토리로 이동한다.

git clone https://github.com/goharbor/harbor-arm.git
cd harbor-arm

3. arm64 이미지 빌드

3-1. Makefile에서 docker-compose version 파싱 실패

에러 메시지

• Failed to parse docker-compose version.

상황/원인 추정

• 내 환경의 docker-compose는 독립 바이너리가 아니라 docker compose 래퍼였고, 출력 포맷이 Harbor Makefile이 기대한 정규식과 달랐다.

내가 시도한 것

• docker compose version / docker-compose version 출력 비교
• Makefile이 어떤 문자열을 기대하는지 확인

수정한 파일/코드

• /usr/local/bin/docker-compose에 “docker compose를 대신 실행하되, docker-compose version 출력만 Harbor Makefile이 파싱 가능한 형태로 맞춰주는 래퍼 스크립트를 덮어썼다.
• 왜 이게 필요했냐?, Harbor 빌드 스크립트/Makefile이 docker-compose version ...의 문자열 포맷을 정규식으로 파싱하는데, 최신 환경에선 docker compose version 출력이 달랐다.

# /usr/local/bin/docker-compose 를 docker compose 래퍼로 교체
cat > /usr/local/bin/docker-compose <<'EOF'
#!/bin/sh
# Harbor Makefile이 기대하는 출력:
#   docker-compose version X.Y.Z
# 를 만들어주고, 나머지는 docker compose로 위임한다.

if [ "$1" = "version" ] || [ "$1" = "--version" ]; then
  v="$(docker compose version --short 2>/dev/null)"
  if [ -z "$v" ]; then
    v="$(docker compose version 2>/dev/null | awk '{print $NF}' | head -n 1)"
  fi
  v="${v#v}"
  echo "docker-compose version $v"
  exit 0
fi

exec docker compose "$@"
EOF

chmod +x /usr/local/bin/docker-compose
hash -r

# 확인
docker-compose version

--

3-2. 디스크 부족으로 빌드 중단

에러 메시지

• No space left on device

상황/원인 추정

• buildx/buildkit이 레이어/스냅샷을 저장하는 도중 루트 파티션 용량 부족으로 깨짐

내가 시도한 것

• df -h, docker info | grep DockerRootDir로 Docker 저장 경로/여유 용량 확인
• 빌드 재시도 시 동일 에러 재현 확인

수정/조치

• VM 저장 위치를 외장 SSD로 옮겨 디스크 여유 확보