기획서: prego-docker GitHub Actions 기반 멀티아키텍처 이미지 빌드 및 Docker Hub 푸시
목적: prego-docker GitHub 레포지토리를 기준으로, 공식 frappe_docker APPS_JSON 빌드 방식을 사용해 Frappe ERPNext v15 + HRMS 커스텀 이미지를 GitHub Actions로 빌드하고 Docker Hub(iamfork/prego-erpnext)에 멀티아키텍처(linux/amd64, linux/arm64)로 푸시하는 기능 개발을 위한 기획·요구사항·산출물을 정의한다. 코드 생성 없음 — 기획·설계·트리·워크플로우 명세만 정리.
prego-docker — Docker 관련 이미지 빌드·설정 및 커스텀 앱 정의를 관리하는 전용 GitHub 레포지토리.
역할
(1) Frappe/ERPNext/HRMS 등 앱 조합 정의(apps.json), (2) 공식 frappe_docker 빌드 파이프라인 활용, (3) GitHub Actions로 빌드·푸시 자동화, (4) 향후 custom app·다른 이미지 변형 추가 시 단일 진입점.
비범위
Ansible 배포·Pulumi 인프라·앱 소스 코드 개발 — 각각 prego-ansible, prego-pulumi, Prego(메인) 등 별도 레포.
2. 아키텍처 제약사항 (필수 준수)
제약
설명
Dockerfile 금지
수동 Dockerfile에서 bench get-app·bench build를 직접 호출하는 방식은 사용하지 않는다.
공식 파이프라인
frappe_docker 리포의 images/custom/Containerfile 빌드 파이프라인을 사용한다.
앱 정의
설치 앱은 apps.json으로만 정의한다.
ERPNext·HRMS 필수
apps.json에 ERPNext와 HRMS를 명시적으로 포함한다.
멀티아키텍처
linux/amd64, linux/arm64 두 플랫폼을 지원한다.
푸시 대상
Docker Hub iamfork/prego-erpnext (단일 레포, 태그로 버전 구분).
3. 목표 저장소 트리 (구현 시 산출물)
prego-docker 레포 루트 기준으로, 구현 후 갖춰질 구조는 아래와 같다.
.
├── apps.json
├── .dockerignore
├── README.md
└── .github/
└── workflows/
└── docker-build.yml
apps.json: 설치할 앱(ERPNext, HRMS)의 url·branch 정의. 빌드 시 Base64 인코딩되어 APPS_JSON_BASE64 빌드 인자로 전달.
README.md: 빌드 원리, 필수 GitHub Secrets, 멀티아키텍처 동작, Hetzner CPX(amd64)에서 사용 방법 설명.
.github/workflows/docker-build.yml: 트리거·QEMU·buildx·로그인·Base64 인코딩·빌드·푸시·태그 전략을 정의하는 워크플로우.
frappe_docker Containerfile 위치: 워크플로우에서 **공식 frappe_docker 리포의 images/custom/Containerfile**을 참조해야 하므로, (1) 해당 파일을 prego-docker에 복사해 두거나, (2) checkout 시 frappe_docker를 서브모듈/별도 checkout으로 가져와 file: 경로를 그쪽으로 지정하는 방식 중 하나로 구현. 기획 단계에서는 구현 시 결정 사항으로 남긴다.
4. apps.json 내용 (필수 정의)
빌드 시 사용할 앱 목록. 순서: ERPNext → HRMS(의존성 순). Frappe는 bench init에 포함되므로 목록에 넣지 않는다.
앱
url
branch
ERPNext
https://github.com/frappe/erpnext
version-15
HRMS
https://github.com/frappe/hrms
version-15
JSON 구조 예시 (구현 시 그대로 사용 가능):
[
{
"url": "https://github.com/frappe/erpnext",
"branch": "version-15"
},
{
"url": "https://github.com/frappe/hrms",
"branch": "version-15"
}
]
Private 리포 사용 시: url에 Personal Access Token을 넣지 말고, 빌드 시점에만 환경변수 등으로 주입하는 방식 권장. GitHub Actions에서는 Secrets로 관리.
버전 변경: version-16 등으로 올릴 때는 branch 값과 아래 빌드 인자 FRAPPE_BRANCH를 함께 맞춘다.
5. 빌드 인자 (Build Args)
인자
값
설명
APPS_JSON_BASE64
워크플로우에서 생성
apps.json 내용을 Base64 인코딩한 문자열. GitHub Actions 단계에서 base64 -w 0 apps.json(Linux) 또는 호환 방식으로 생성 후 GITHUB_ENV 또는 build-arg로 전달.
FRAPPE_BRANCH
version-15
Frappe 프레임워크 브랜치. ERPNext·HRMS 브랜치와 동일하게 유지.
PYTHON_VERSION
3.11
Python 버전. Frappe v15 호환.
6. GitHub Actions 워크플로우 설계 (docker-build.yml 요구사항)
구현 시 작성할 워크플로우가 충족해야 할 요구사항만 정리. 실제 YAML 코드는 구현 단계에서 작성.
6.1 트리거
트리거
동작
push (branches)
기본 브랜치(예: main) 푸시 시 빌드·푸시 실행.
(선택) tag push
v* 시맨틱 태그 푸시 시 해당 버전 태그로 이미지 푸시. 구현 시 workflow_dispatch 등 추가 가능.
6.2 필수 단계 (순서)
순서
단계
액션/내용
1
Checkout
actions/checkout@v4 — prego-docker 레포 체크아웃.
2
Set up QEMU
docker/setup-qemu-action@v3 — linux/arm64 등 비호스트 아키텍처 에뮬레이션.
포함 권장 제외 대상: .git, README.md, docs, .github, *.md, 로컬 테스트 스크립트 등. apps.json은 빌드 인자로 Base64 전달하므로 컨텍스트에 반드시 넣을 필요는 없지만, 인코딩 단계에서 읽기 위해 레포에는 포함. (컨텍스트에 포함해도 무방.)
구현 시 frappe_docker 쪽에서 복사한 파일만 쓸 경우, prego-docker 루트 기준으로 최소한의 파일만 컨텍스트에 들어가도록 .dockerignore를 작성.
