English {#english}

Frappe/ERPNext/HRMS v15 → v16 Upgrade Plan

Purpose: Organize work needed to move the Prego stack (Frappe, ERPNext, HRMS) from version-15 to version-16 by phase.
No code generation — plan, strategy, dependencies, verification checklist only.

References: docker-hub-stack-ansible-deploy-plan; prego-docker-implementation-plan; ansible-frappe-bench-rc127-resolution-plan.

1. Requirements: v15 vs v16

Stack: Python 3.12+ (v16 required), Node 24, MariaDB 10.6+ (10.11 recommended), Redis 6+ (7-alpine), Debian 13+ or Ubuntu 24.04+, Yarn 1.22+, pip 25.3+. v16 changes: app release sync; built-in vector search (optional); Traefik v3; higher resource use (AI/background); Frappe Cloud private bench logic.

2–4. Scope, phases (summary)

§2 Impact: prego-docker (Dockerfile, apps.json, FRAPPE_BRANCH=version-16, Python 3.12+, Node 24); prego-ansible (MariaDB 10.11, frappe_version=version-16, v16 image, resource limits); prego-saas-app (v16 API, install_requires); prego-pulumi (OS image optional); docs.
§3 Phase 0: Prereqs and risk (Python/Node/MariaDB/OS/frappe_docker v16, v15→v16 migration guide, vector search optional). Phase 1: prego-docker v16 image (base 3.12, Node 24, FRAPPE_BRANCH=version-16, apps.json version-16, bench init check, Trivy, optional Traefik v3). Phase 2: prego-ansible (mariadb:10.11, redis 7-alpine, frappe_version version-16, v16 app image, resource limits). Phase 3: prego-saas-app v16 compatibility (setup.py, Doctypes, hooks). Phase 4: Staging deploy and test. Phase 5: Production rollout and rollback plan.

Full tables (§1–§4) and exact wording are in the Korean section below.

한국어 {#korean}

Frappe/ERPNext/HRMS v15 → v16 업그레이드 기획서

목적: Prego 스택(Frappe·ERPNext·HRMS)을 version-15에서 version-16으로 전환하기 위해 필요한 작업을 Phase별로 정리한다.
코드 생성 없음 — 기획·전략·의존성·검증 체크리스트만 명세.

참조:

docker-hub-stack-ansible-deploy-plan.md — v15 추천 스택
prego-docker-implementation-plan.md — prego-docker 구조
ansible-frappe-bench-rc127-resolution-plan.md — bench init·이미지 연동

1. 요구사항 비교: v15 vs v16

컴포넌트	v15 (현행)	v16 (목표)	비고
Python	3.10 또는 3.11	3.12+ (3.14 지원 포함)	v16 필수 요구사항. 멀티테넌트 시 모든 사이트가 동일 런타임 충족. Python 3.12는 이미 가용.
Node.js	18.x 또는 20.x	24	LTS 전환, Vite·빌드 호환성 검증 필요.
MariaDB	10.6	10.6+ (권장 10.11)	v16은 10.6+ 멀티테넌트 성능 최적화. 공식 예시는 `mariadb:10.11`. 11.8 필수 아님.
Redis	6.2 또는 7.x	6+ (7-alpine 권장)	현행 Redis 7 유지. 공식 예시 `redis:7-alpine`.
OS	Debian 12 (bookworm)	Debian 13+ 또는 Ubuntu 24.04+	베이스 이미지·Hetzner 지원 확인.
Yarn	1.x	1.22+
pip	기존	25.3+	uv·bench 의존성 해석 영향.

1.1 v16 멀티테넌트·배포 관련 주요 변화

항목	v15	v16	Prego 영향
앱 버전 동기화	ERPNext·HRMS·Payments 버전 불일치 다수	공식 앱 릴리즈 주기 동기화	Bench Update 시 멀티사이트 호환성 예측 용이.
벡터 검색	없음	내장 벡터 DB 지원	AI 기반 검색 사용 시 테넌트별 검색 인덱스 별도 관리 필요.
Docker/Traefik	Traefik v2 기준	Traefik v3 최적화	SSL(Let’s Encrypt) 레이블 개선, DNS 기반 테넌트 추가 시 전체 스택 재시작 불필요.
자원 할당	기존 수준	AI·백그라운드 작업으로 자원 사용 증가	테넌트 컨테이너별 CPU/RAM 제한 세밀 조정 필요. resource-optimization-safe-adoption-plan.md 연동.
Frappe Cloud	-	Private Bench 로직 강화	v16/v15 테넌트 격리·라이브러리 충돌 회피. Prego 자체 배포 시 참고.

2. 영향 범위 (레포·역할별)

레포/역할	변경 대상	상세
prego-docker	Dockerfile, apps.json, build.yml	Python 3.12+, Node 24, FRAPPE_BRANCH=version-16, apps.json branch 수정, (선택) Traefik v3·compose
prego-ansible	mariadb_server, redis_server, frappe_bench	MariaDB 10.11, frappe_version=version-16, frappe_bench_image(v16 이미지), 자원 제한 세밀화
prego-saas-app	setup.py, pyproject.toml, Doctype·후크	v16 API·동작 변경 대응, install_requires 호환
prego-pulumi	(선택) OS·이미지	Ubuntu 24.04+ 또는 Debian 13 VM 템플릿
Prego/docs	docker-hub-stack-ansible-deploy-plan 등	v16 스택으로 문서 갱신

3. Phase별 작업 계획

Phase 0: 선행 조건·리스크 검토 (코드 변경 없음)

순서	작업	목표	비고
0.1	Python 3.12+	Docker Hub `python:3.12-slim-*` 존재·안정성 확인	v16 필수. 3.12는 이미 가용. 3.14 지원은 선택.
0.2	Node 24 LTS	Node 24 공식 지원·NVM 설치 가능 여부 확인	prego-docker NVM install 스크립트 호환.
0.3	MariaDB 10.6→10.11	`mariadb:10.11` Docker 이미지·10.6→10.11 마이그레이션 경로 확인	v16 공식 예시는 10.11. 10.6+ 요구이므로 10.11 권장.
0.4	Debian 13 / Ubuntu 24.04	Hetzner·Pulumi에서 사용 가능한 OS 이미지 확인	bookworm → trixie 또는 Ubuntu 24.04 전환.
0.5	frappe_docker v16	frappe_docker `images/custom` v16 지원·Containerfile 패턴·Traefik v3 확인	Vendoring 대상 최신화. Traefik v3 레이블 패턴 검토.
0.6	기존 테넌트 DB	v15 사이트 → v16 마이그레이션 공식 가이드·breaking changes 정리	Frappe Forum v15→v16 가이드 참조.
0.7	벡터 검색 (선택)	v16 벡터 DB·AI 검색 사용 시 테넌트별 인덱스 관리 전략	사용하지 않으면 생략 가능.

Phase 1: prego-docker v16 이미지 빌드

순서	작업	파일/위치	상세
1.1	베이스 이미지	Dockerfile	`ARG PYTHON_VERSION=3.12` (v16 필수 3.12+). `python:3.12-slim-bookworm` 또는 trixie/Ubuntu 24.04 기반.
1.2	Node 버전	Dockerfile	`ARG NODE_VERSION=24`, NVM install v24.
1.3	Frappe 브랜치	Dockerfile, build.yml	`ARG FRAPPE_BRANCH=version-16`, `FRAPPE_PATH` 유지.
1.4	apps.json	apps.json	`erpnext`, `hrms` branch를 `version-16`으로 변경. crm, drive는 `develop` 브랜치(v16 호환, version-16 브랜치 없음). prego-saas-app은 v16 호환 태그 사용.
1.5	wkhtmltopdf	Dockerfile	v16 요구 0.12.6 호환 여부 확인. 필요 시 버전·경로 조정.
1.6	bench init 검증	build.yml, tests	`bench init` 성공·6개 앱(frappe, erpnext, hrms, crm, drive, prego_saas_app) 존재 확인.
1.7	Trivy 스캔	trivy-scan.yml	새 베이스·의존성 기준 CVE 재평가. Critical 0 정책 유지.
1.8	(선택) Traefik v3·compose	compose, docs	v16 공식 예시는 Traefik v3 레이블·DNS 멀티테넌트. saas-frappe-build-templates-and-runbook.md 갱신 시 반영.

산출물: iamfork/prego-repo v16 태그 이미지 (linux/amd64, linux/arm64).

Phase 2: prego-ansible v16 스택 반영

순서	작업	역할/파일	상세
2.1	MariaDB 10.11	mariadb_server/defaults/main.yml	`mariadb_image: mariadb:10.11`. v16 공식 예시 기준. 10.6→10.11 마이그레이션 시 별도 Runbook.
2.2	Redis	redis_server/defaults/main.yml	v16은 Redis 6+ 요구. 현행 `redis_version: "7"` (7-alpine) 유지. 공식 예시와 동일.
2.3	Frappe 버전	frappe_bench/defaults/main.yml	`frappe_version: version-16`.
2.4	앱 이미지	playbook.yml, inventory	`frappe_bench_image: iamfork/prego-repo:v16-YYYYMMDD` 또는 digest 고정.
2.5	bench init vs 이미지	frappe_bench/tasks	iamfork/prego-repo 사용 시 bench init 생략·sites만 마운트하는 흐름인지 확인. v16 이미지에 apps 포함 전제.
2.6	자원 제한 세밀화	frappe_bench, compose	v16은 AI·백그라운드 작업으로 자원 사용 증가. 테넌트 컨테이너별 CPU/RAM 제한 조정. resource-optimization-safe-adoption-plan.md 연동.
2.7	(선택) Traefik v3	nginx·proxy 설정	DNS 멀티테넌트·SSL 레이블 개선. 전체 스택 재시작 없이 신규 테넌트 추가 가능.
2.8	문서	docker-hub-stack-ansible-deploy-plan.md	v16 추천 스택(MariaDB 10.11, Node 24, Python 3.12+)으로 갱신.

Phase 3: prego-saas-app v16 호환

순서	작업	파일	상세
3.1	API·Doctype 호환	전체	Frappe v16 breaking changes·deprecated API 정리. Doctype·Client Script·Server Script 검토.
3.2	install_requires	setup.py, pyproject.toml	frappe는 계속 제외. 기타 의존성 v16과 충돌 여부 확인.
3.3	테스트	CI, 로컬	v16 bench에서 `bench run-tests --app prego_saas_app` 실행.
3.4	태그	prego-saas-app	v16 호환 버전 태그(예: v1.1.0) 생성. apps.json에 반영.
3.5	(선택) 벡터 검색	prego-saas-app	v16 AI 기반 검색 사용 시 테넌트별 검색 인덱스 관리 전략 수립. 미사용 시 생략.

Phase 4: 기존 테넌트 마이그레이션 (선택)

순서	작업	대상	상세
4.1	DB 백업	모든 테넌트	R2·로컬 백업 확인. mariadb-backup-r2.md
4.2	MariaDB 10.6→10.11	DB 서버	새 10.11 인스턴스 생성·덤프 복원 또는 in-place upgrade. v16 공식 예시는 10.11. 마이그레이션 Runbook 작성.
4.3	bench migrate	각 사이트	`bench switch-to-branch version-16 frappe erpnext hrms crm drive`, `bench update --patch`, `bench migrate`, `bench build`, `bench restart`. v16 앱 버전 동기화로 멀티사이트 업데이트 예측 용이.
4.4	롤백 계획	Runbook	실패 시 v15 이미지·MariaDB 10.6으로 복귀 절차.

4. 의존성·순서 요약

Phase 0 (선행) → Phase 1 (prego-docker) → Phase 2 (prego-ansible) → Phase 3 (prego-saas-app) → Phase 4 (마이그레이션)
     │                    │                         │                           │
     └─ Python 3.12+, Node 24, MariaDB 10.11, OS·Traefik v3 가용성
                         └─ iamfork/prego-repo:v16 이미지
                                              └─ Ansible 변수·이미지 태그·자원 제한
                                                                  └─ prego-saas-app v16 호환
                                                                                    └─ 기존 사이트 DB·앱 업그레이드

5. 리스크·대응

리스크	영향	대응
Python 3.12 호환성	Phase 1 지연	v16 필수 3.12+. 3.12는 이미 가용. 3.14는 선택.
MariaDB 10.6→10.11 마이그레이션 실패	데이터 손실	백업 필수. 스테이징에서 10.6→10.11 덤프/복원 검증.
prego-saas-app v16 비호환	빌드·런타임 오류	Phase 3에서 API 변경·테스트 선행.
frappe_docker v16 패턴 변경	Dockerfile Vendoring 실패	Phase 0.5에서 최신 frappe_docker·Traefik v3 확인.
기존 테넌트 다운타임	서비스 중단	Blue/Green·점진적 전환 검토.
v16 자원 사용 증가	OOM·성능 저하	테넌트별 CPU/RAM 제한 세밀 조정. resource-optimization 연동.

6. 검증 체크리스트

Phase 1 완료 시

prego-docker bench init 성공 (Python 3.12+, Node 24, version-16).
iamfork/prego-repo:v16-* 이미지 빌드·푸시 성공.
Verify image apps: frappe, erpnext, hrms, crm, drive, prego_saas_app 존재.
Trivy 스캔 Critical 0.

Phase 2 완료 시

Ansible playbook으로 v16 스택 배포 성공 (MariaDB 10.11, Redis 7, 앱 이미지 v16).
bench new-site · bench install-app erpnext hrms crm drive prego_saas_app 성공.
테넌트 컨테이너별 자원 제한(CPU/RAM) 적용·모니터링.

Phase 3 완료 시

prego-saas-app v16 bench에서 테스트 통과.
프로비저닝 플로우(신규 사이트 생성) 정상 동작.

Phase 4 완료 시 (해당 시)

기존 테넌트 DB 마이그레이션 성공.
bench migrate 오류 없음.
롤백 절차 문서화·검증.

7. 참고 자료

Frappe v16 Installation — 공식 요구사항.
ERPNext v15→v16 Upgrade Guide (Debian 12)
ERPNext Quick Install v16 (Python 3.14 + Node 24)
saas-frappe-build-templates-and-runbook.md — v16 Traefik v3·DNS 멀티테넌트 compose 패턴 반영 시 참조.

7.1 v16 Docker Compose 참고 (공식 예시)

v16 공식 예시는 frappe/erpnext:v16.6.1, mariadb:10.11, redis:7-alpine, Traefik v3 레이블 기반 DNS 멀티테넌트. Prego는 iamfork/prego-repo 커스텀 이미지 사용하나, sites 볼륨·Traefik Host 규칙·bench new-site 흐름은 동일 패턴 적용 가능.

8. 요약

Phase	목표	핵심 변경
0	선행 조건 확보	Python 3.12+·Node 24·MariaDB 10.11·OS·Traefik v3·frappe_docker v16 확인
1	prego-docker v16 이미지	Dockerfile(Python 3.12+, Node 24), apps.json(version-16), (선택) Traefik v3 compose
2	prego-ansible v16 스택	MariaDB 10.11, frappe_version=version-16, frappe_bench_image v16, 자원 제한 세밀화
3	prego-saas-app v16 호환	API·테스트·태그, (선택) 벡터 검색
4	기존 테넌트 마이그레이션	MariaDB 10.6→10.11, bench migrate·롤백 Runbook

권장 진행 시점: Phase 0 완료(Python 3.12·MariaDB 10.11·frappe_docker v16 확인) 후 Phase 1 착수. Phase 0 완료 전 코드 변경 지양.