Golden Image

배포와 기반 업데이트

빌드한 ZIP을 Mothership에 올리고, 고정된 프로필로 새 앱을 만들고, 앱 작성자의 변경을 지키며 기반(SDK·빌드 도구)을 올려요.

Mothership에 올리기

구성 할 일
프런트엔드만(권장) frontend/dist/<release>.zip을 업무 앱 → 카탈로그 관리 → 앱 추가에 올려요. 후보가 되고, 버전·환경에서 공동 검증과 운영에 반영해요
프런트엔드 + 백엔드 ZIP을 올리고, 백엔드를 외부 백엔드 연결 · 고급으로 연결해요. 환경마다 설치하고 대상을 정해요
백엔드만 백엔드를 URL과 서명 키로 연결해요

선언한 record_schema/value_schema는 게이트웨이가 모든 쓰기에 적용해요. 자세한 흐름은 Mothership: 앱 올리기와 배포에 있어요.

갈피와 같이

갈피 프로젝트를 Mothership 앱에 이으면, 채팅의 에이전트가 이 저장소를 고치고, 갈피가 소스를 Mothership에 보내요. 빌드는 Mothership의 소스 빌드 실행기가 하고, 갈피는 그 빌드로 미리보기와 검토 후보를 요청해요. 새 앱의 첫 소스와 기반 업데이트에는 갈피 운영자가 GALPI_MOTHERSHIP_PROFILES_FILE로 정한 승인 프로필 목록을 써요. Galpi 연결 없이 CLI와 ZIP 업로드만으로도 모든 것이 돼요. → 제품 잇기

공식 프로필로 새 앱 만들기

프로필은 기반의 한 판을 고정한 묶음이에요. 기본 프로필은 minimal(최소 앱, 프런트엔드)이고, 문서 검토 예제는 --frontend-profile document-review, Python/Node는 --runtime backend 또는 --runtime backend-node로 골라요.

bash
python scripts/template_profiles.py pack . /tmp/profile-v1 --version 1.0.0
# 출력한 SHA-256을 써요
python scripts/template_profiles.py verify /tmp/profile-v1 --sha256 HASH
python scripts/template_profiles.py init /tmp/profile-v1 /tmp/my-app --sha256 HASH --package-slug sales-desk
  • profile digest는 profile.json의 SHA-256(소문자 hex)이에요. Mothership의 승인 목록과 갈피의 목록이 이 값과 그대로 비교해요.
  • --package-slug는 갈피와 같은 규칙으로 앱 id를 정해요: 프런트엔드 agent.id는 <slug>, 백엔드는 <slug>-backend. Mothership 소스 빌드는 프런트엔드 agent.id가 앱의 packageSlug와 같아야 해요.
  • 앱의 .mothership-template.json이 생성 프로필 digest와 관리 파일의 기준 내용을 가져요. SDK, 계약, 빌드 스크립트가 관리 대상이고, 제품 소스와 앱 manifest는 앱 작성자의 파일이에요.

기반 업데이트

bash
# 내 작업을 먼저 커밋하고 따로 된 브랜치에서
git switch -c update/mothership-v2
python scripts/template_profiles.py update /opt/profiles/v2 . --sha256 HASH
make build && make check && make test

업데이트가 적용되면 모든 관리 파일이 새 프로필의 파일과 바이트 단위로 같아요.

  • 앱이 고치지 않은 관리 파일은 새 내용으로 바꿔요. 앱이 고친 관리 파일은 3-way merge가 정확히 새 프로필 파일이 될 때만 적용해요.
  • 충돌이 하나라도 있으면 아무 파일도 바꾸지 않고 .mothership-update/conflicts.json과 새 프로필의 파일(.mothership-update/<경로>)을 남겨요. 앱 고유의 변경을 앱 코드나 AGENTS.md로 옮기고 같은 명령을 다시 돌려요.
  • 같은 계약 주 버전 안의 업데이트만 해요. 다른 주 버전으로 저절로 옮기지 않아요.
  • Mothership 운영자가 MOTHERSHIP_REPOSITORY_PROFILES_FILE을 두면, 소스 빌드는 승인한 프로필과 관리 파일이 그대로인 앱만 받아요.

폐쇄망 고객사

중앙에서 Golden Image 프로필을 발행하고 고객사로 반입해요. 발행 manifest에는 release id와 순번, source commit, 모든 프로필의 id·버전·digest·parts·계약 버전, 지원하는 Mothership·갈피 범위, 이미지·패키지 digest와 SBOM을 고정해요. 같은 버전 이름으로 내용을 바꾸지 않아요. 소스만 반입해서는 안 되는 부분(npm 의존성, 글꼴, 빌드 이미지)과 고객사 내부 주소 연결은 저장소의 docs/air-gapped-distribution.md에 있어요. 앱은 CDN에서 아무것도 받지 않아서 같은 빌드가 폐쇄망에서도 돌아요.

Esc