139 lines
7.6 KiB
Markdown
139 lines
7.6 KiB
Markdown
# Implementation Plan — 배포 스크립트 URL 파라미터화 (Rev.1)
|
||
|
||
- **작성자**: Planner Agent
|
||
- **날짜**: 2026-07-09
|
||
- **상태**: Draft (사용자 승인 대기)
|
||
- **관련 리뷰 피드백**: Reviewer A 이식성(portability) 스캔 결과
|
||
|
||
---
|
||
|
||
## 1. 배경 및 문제 정의
|
||
|
||
Reviewer A의 코드베이스 스캔 결과, 배포 스크립트에 배포 원본(origin) URL 3개가 하드코딩되어 있어
|
||
포크/미러/사설 Gitea 인스턴스 환경으로의 이식성이 저해됨이 확인되었습니다.
|
||
|
||
| # | 위치 | 변수 | 현재 하드코딩 값 |
|
||
|---|------|------|------------------|
|
||
| 1 | `deploy/install.sh:57` | `REPO_URL` | `https://git.godopu.com/tmpl/multi-agent-mux.git` |
|
||
| 2 | `deploy/install.sh:58` | `ARCHIVE_URL` | `https://git.godopu.com/tmpl/multi-agent-mux/archive/main.tar.gz` |
|
||
| 3 | `deploy/update.sh:138` | `INSTALLER_URL` | `https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh` |
|
||
|
||
그 외 스크립트(`lib.sh`, `create_session.sh` 등)는 상대 경로 및 `TARGET_DIR` 파라미터화가
|
||
올바르게 적용되어 있어 이번 변경 범위에서 제외합니다.
|
||
|
||
## 2. 목표 (Goals)
|
||
|
||
1. 위 3개 URL을 환경변수 `MAM_REPO_URL`, `MAM_ARCHIVE_URL`, `MAM_INSTALLER_URL`로
|
||
오버라이드 가능하게 파라미터화하되, **미설정 시 현재 값을 그대로 기본값으로 유지**한다
|
||
(기존 사용자에 대한 동작 변경 0).
|
||
2. 세 변수를 `.env.example`과 `deploy/README.md`에 문서화한다.
|
||
3. 검증 절차를 명문화하여 Developer가 DoD 자가 검증에 사용할 수 있게 한다.
|
||
|
||
### Non-Goals (이번 범위 제외)
|
||
|
||
- `README.md`/`BOOTSTRAP*.md` 본문의 원라이너 예시 URL 자체를 변수화하는 것
|
||
(문서상의 예시는 실제 기본 배포 원본이므로 그대로 둔다).
|
||
- deploy 스크립트가 `.env` 파일을 직접 파싱/소싱하도록 만드는 것 (§3.4 설계 결정 참조).
|
||
- URL 간 파생 로직 (예: `MAM_REPO_URL`로부터 archive URL 자동 조립) — §3.5 참조.
|
||
|
||
## 3. 설계 (Design)
|
||
|
||
### 3.1. `deploy/install.sh` 수정
|
||
|
||
57–58행을 bash 기본값 확장 패턴으로 교체:
|
||
|
||
```bash
|
||
REPO_URL="${MAM_REPO_URL:-https://git.godopu.com/tmpl/multi-agent-mux.git}"
|
||
ARCHIVE_URL="${MAM_ARCHIVE_URL:-https://git.godopu.com/tmpl/multi-agent-mux/archive/main.tar.gz}"
|
||
```
|
||
|
||
### 3.2. `deploy/update.sh` 수정
|
||
|
||
138행을 동일 패턴으로 교체:
|
||
|
||
```bash
|
||
INSTALLER_URL="${MAM_INSTALLER_URL:-https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh}"
|
||
```
|
||
|
||
**체이닝 전파 주의**: `update.sh`는 140–142행에서 `curl ... | bash -s --`로 새 installer를
|
||
실행한다. 호출자가 `MAM_REPO_URL=x bash update.sh` 형태(명령 접두 대입)로 실행하면 해당
|
||
변수는 프로세스 환경에 export되어 자식 bash에 자동 상속되므로 별도 재-export 코드는
|
||
불필요하다. 단, 이 상속 동작이 계약임을 스크립트 주석 및 문서에 명시한다.
|
||
|
||
### 3.3. `.env.example` 문서화
|
||
|
||
새 섹션 `# deploy / distribution source`를 추가하고 기존 파일의 서식 규약
|
||
(`#default:` 라인 + 주석 처리된 변수 예시)을 따른다. **핵심 주의 문구**를 반드시 포함:
|
||
|
||
> 이 변수들은 deploy 스크립트가 **프로세스 환경에서** 읽는다. `install.sh`는 워크스페이스에
|
||
> `.env`가 생기기 전(curl 원라이너) 실행될 수 있고 deploy 스크립트는 `.env`를 파싱하지
|
||
> 않으므로, `export MAM_REPO_URL=...` 또는 명령 접두 대입으로 전달해야 한다.
|
||
|
||
### 3.4. 설계 결정: `.env` 소싱을 하지 않는 이유
|
||
|
||
- `install.sh`는 설치 대상 디렉터리에 파일이 존재하기 전에 실행되므로 `.env` 의존이 불가능.
|
||
- `.env`를 `source`하면 임의 셸 코드 실행 경로가 생겨 보안·부작용 리스크 발생.
|
||
- 따라서 세 변수 모두 **환경변수 단일 경로**로 통일하고, `.env.example`에는
|
||
"문서화 + 사용법 안내" 목적으로만 등재한다.
|
||
|
||
### 3.5. 설계 결정: 변수 간 파생 없음
|
||
|
||
`MAM_REPO_URL`에서 archive/raw URL을 자동 조립하지 않는다. Gitea(`/archive/main.tar.gz`,
|
||
`/raw/branch/main/`)와 GitHub(`/archive/refs/heads/main.tar.gz`, `raw.githubusercontent.com`)의
|
||
URL 스킴이 상이하여 파생 로직이 오히려 이식성을 해친다. 세 변수는 독립이며, 미러 운영 시
|
||
**셋을 함께 설정**하도록 문서에 권고 문구를 넣는다.
|
||
|
||
### 3.6. `deploy/README.md` 문서화
|
||
|
||
"How to Install and Deploy" 섹션에 미러/포크 설치 예시를 추가:
|
||
|
||
```bash
|
||
# Installing from a fork/mirror
|
||
curl -fsSL https://my-mirror.example.com/.../install.sh \
|
||
| MAM_REPO_URL=https://my-mirror.example.com/me/multi-agent-mux.git \
|
||
MAM_ARCHIVE_URL=https://my-mirror.example.com/me/multi-agent-mux/archive/main.tar.gz \
|
||
bash
|
||
|
||
# Updating against a mirror
|
||
MAM_INSTALLER_URL=https://my-mirror.example.com/.../install.sh bash deploy/update.sh
|
||
```
|
||
|
||
(파이프 실행 시 접두 대입은 `bash` 쪽에 붙여야 함을 예시로 보여준다.)
|
||
|
||
## 4. 파급 범위 및 리스크 분석
|
||
|
||
| 리스크 | 평가 | 완화책 |
|
||
|--------|------|--------|
|
||
| 기본값 오타로 기존 설치 경로 파손 | 중 | 검증 §5-3에서 기본값 문자열이 변경 전과 byte-identical한지 diff/grep으로 확인 |
|
||
| ShellCheck 경고 (SC2154 등) | 낮음 | `${VAR:-default}` 패턴은 미정의 변수 경고 없음. CI(`gitea-ci.yml`)의 shellcheck 단계로 확인 |
|
||
| `update.sh` 체이닝 시 오버라이드 미전파 | 중 | §3.2 상속 계약 주석 명시 + 검증 §5-5 |
|
||
| 문서-코드 정합성 (변수명 불일치) | 낮음 | task.md DoD에 변수명 3종 교차 대조 항목 포함 |
|
||
|
||
## 5. 검증 절차 (Verification Steps)
|
||
|
||
Developer는 커밋 전 아래를 순서대로 수행하고 결과를 리뷰 요청에 첨부한다.
|
||
|
||
1. **문법 검사**: `bash -n deploy/install.sh deploy/update.sh` — 종료코드 0.
|
||
2. **린트**: `shellcheck deploy/install.sh deploy/update.sh` — 신규 경고 0 (CI와 동일 조건).
|
||
3. **기본값 무결성**: `grep -n 'MAM_\(REPO\|ARCHIVE\|INSTALLER\)_URL' deploy/*.sh` 출력에서
|
||
`:-` 뒤 기본값 3개가 변경 전 하드코딩 문자열과 정확히 일치하는지 확인.
|
||
4. **오버라이드 동작 (install.sh)**: 빈 스크래치 디렉터리에서
|
||
`MAM_ARCHIVE_URL=https://127.0.0.1:1/nope.tar.gz bash deploy/install.sh <scratch-dir>`
|
||
실행 → fetch 단계가 오버라이드된 URL로 시도하다 실패하는지 확인
|
||
(`bash -x` 트레이스에서 `ARCHIVE_URL` 해석값 확인). **실제 워크스페이스에서 실행 금지.**
|
||
5. **오버라이드 동작 (update.sh)**: `update.sh`는 기존 설치를 파괴적으로 제거하므로
|
||
전체 실행 대신 `bash -x` 트레이스를 138행 부근에서 조기 중단(Ctrl-C 또는 read 삽입 없이
|
||
확인 후 `--force` 미사용)하거나, 디스포저블 스크래치 설치본에서만 end-to-end 수행.
|
||
최소 기준: `MAM_INSTALLER_URL` 접두 대입 시 `INSTALLER_URL` 해석값이 오버라이드와 일치.
|
||
6. **회귀 (기본 경로)**: 리포지토리 루트에서 `bash deploy/install.sh` 재실행 →
|
||
`check_assets_present`가 충족되어 네트워크 fetch 없이 기존과 동일하게 완료되는지 확인.
|
||
7. **문서 정합**: `.env.example`·`deploy/README.md`에 세 변수명이 스크립트와 철자까지
|
||
일치하게 등재되었는지 교차 확인.
|
||
|
||
## 6. 산출물 및 커밋 규약
|
||
|
||
- 변경 파일: `deploy/install.sh`, `deploy/update.sh`, `.env.example`, `deploy/README.md`
|
||
- 단일 원자적 커밋, 메시지 제안:
|
||
`feat(deploy): parameterize distribution URLs via MAM_*_URL env vars`
|
||
- 완료 후 Reviewer A(논리 정합) / Reviewer B(구현 세부) 이중 리뷰 → 양측 PASS 시 마감.
|