배포 실행 가이드 · 2026-11-18
로컬 self-hosted runner로
Dev 배포하기
마지막 업데이트 2026-11-18
대상: 사무실 Mac mini runner(ppi-local-build-pc)로 브랜치 Dev 환경을 배포하려는 개발자
Dev 배포(dev.yml)는 feature/local-build 브랜치에서 runner=ppi-local-build를 고르면 이 PC에서 끝까지 실행된다. 2026-11-18 세 번째 실행(run 44244026986)에서 빌드, GHCR push, Terraform apply, 헬스 체크까지 성공했다.
Staging·Prod 배포는 Linux 전용 단계와 self-hosted 고정 러너 때문에 이 PC에서 실행할 수 없다. runner 등록 절차는 로컬 self-hosted runner로 PPI 빌드 실험하기를 따른다.
1. 이 PC 환경을 확인한다
| 항목 | 값 |
|---|---|
| 하드웨어·OS | Mac mini, Apple Silicon(arm64), 8코어, RAM 8 GB, macOS 26.5.2 |
| runner | ~/actions-runner, v2.338.2, 이름 ppi-local-build-pc, 라벨 ppi-local-build 하나(--no-default-labels) |
| Docker | Docker Desktop, CLI 29.9.3. VM 메모리 6 GB, Swap 4 GB, CPU 8 |
| CLI 도구 | aws·node(Homebrew), jq·python3(3.9)·openssl(macOS 기본). Terraform과 gh는 job이 설치 |
| 실행 방식 | 터미널의 ./run.sh(서비스 미등록). 배포 중 터미널을 닫으면 job이 실패한다 |
Docker VM 메모리 기본값(약 4 GB)에서는 web·socket 동시 빌드가 메모리 부족으로 중단된다. Docker Desktop의 Settings → VM resources에서 Memory 6 GB, Swap 4 GB로 둔다. PC 전체가 8 GB이므로 6 GB보다 높이지 않는다.
2. 브랜치와 runner를 골라 실행한다
dev.yml은 수동 실행 워크플로이고 실행할 때 고른 브랜치의 워크플로 파일을 사용한다. runner 입력은 feature/local-build에만 있다.
| 폼 항목 | 값 |
|---|---|
| Use workflow from | feature/local-build |
| Action to perform | deploy 또는 destroy |
| runner | ppi-local-build(기본값 self-hosted는 기존 러너) |
| 나머지 체크박스 | 그대로(false) |
gh workflow run dev.yml --ref feature/local-build -f action=deploy -f runner=ppi-local-build
브랜치 전용 환경(feature-local-build-dev.dubuhealth.in)이 실제 AWS에 생긴다. 테스트가 끝나면 같은 runner로 정리한다.
gh workflow run dev.yml --ref feature/local-build -f action=destroy -f runner=ppi-local-build
3. job별 실행 위치
| job | 실행 위치 | 하는 일 |
|---|---|---|
| lifecycle-begin | GitHub hosted | 브랜치 배포 lock 획득, 소유자 확인 |
| deploy | 이 PC | gh·Terraform 설치, web·socket 이미지 linux/arm64 빌드와 GHCR push, OIDC로 Dev AWS 인증, Terraform plan·apply, 앱 헬스 체크 |
| destroy | 이 PC | Terraform destroy와 남은 리소스 정리 |
| lifecycle-finish | GitHub hosted | 결과 기록, lock 해제 |
Dev OIDC 역할의 신뢰 조건은 저장소와 브랜치(repo:Dobraindev/ppi:ref:refs/heads/*)만 확인하므로 실행한 runner와 관계없이 인증된다. Dev EC2(t4g)와 이 PC가 모두 arm64라 에뮬레이션 없이 빌드한다.
4. feature/local-build에서 바꾼 것
커밋 84bc91fa "ci: Dev 배포를 로컬 macOS 빌드 러너에서 실행할 수 있게 한다".
- runner 선택:
dev.yml에runner입력(self-hosted기본,ppi-local-build)을 추가하고 deploy·destroy job을runs-on: ${{ inputs.runner || 'self-hosted' }}로 바꿨다. 기본값이 그대로라 기존 실행에는 영향이 없다. - gh 설치:
scripts/setup-dev-gh.sh가 Linux만 허용하던 것을 macOS ARM64용 gh 2.102.0 zip도 받도록 했다. 체크섬은 공식 checksums 파일 값으로 고정했다. macOS의sha256sum은--check --status를 지원하지 않아shasum -a 256을 쓴다. - Docker 연결: 워크플로가
DOCKER_CONFIG를 임시 디렉터리로 바꾸면 Mac에서는 buildx 플러그인과 Docker Desktop 소켓을 잃는다(docker: unknown command: docker buildx,/var/run/docker.sock연결 실패). macOS runner에서만~/.docker/cli-plugins를 연결하고DOCKER_HOST=unix://$HOME/.docker/run/docker.sock을 지정한다. 둘 중 하나가 없으면 빌드 전에 오류로 멈춘다. - 테스트:
scripts/setup-dev-gh.test.mjs에 macOS 정상·실패 5종을, 새scripts/dev-local-runner.test.mjs에 runner 입력과 Docker 설정 단계(Linux·macOS 정상·실패) 검증을 추가했다. 배포 job 안에서도 실행된다.
5. 실행 기록
| run | 결과 | 원인과 조치 |
|---|---|---|
| 44238383191 | 실패 | 이미지 빌드 3분 30초 후 ResourceExhausted … cannot allocate memory. Docker VM 메모리 약 4 GB에서 web·socket이 동시에 mediasoup(OpenSSL 포함)을 8코어로 컴파일했다. Docker 메모리를 6 GB, Swap을 4 GB로 올렸다. AWS 단계 전이라 인프라 변경은 없었다. |
| 44239901798 | 실패 | 빌드(22분, 캐시 없음)·AWS 인증·preflight·terraform init은 성공. terraform plan에서 EC2 조회 3건이 lookup ec2.ap-northeast-2.amazonaws.com: no such host로 실패했다. 같은 시점의 STS·KMS·ELB·Route53 조회는 성공했다. 공유기 DNS(192.168.0.1)의 일시 장애로 판단하고 재실행했다. Terraform state lock 문제는 아니었다. |
| 44244026986 | 성공 | deploy job 약 5분 30초. 빌드·push 22초(GHCR registry 캐시), Terraform 1분 24초, 앱 준비 대기 3분 8초. /api/health HTTP 200. |
빌드 시간은 GHCR buildcache 적중 여부에 크게 좌우된다. 의존성이 바뀌어 캐시를 못 쓰면 20분 이상 걸리고 메모리도 한도에 가까워진다(두 번째 실행 중 buildkit 컨테이너 약 4.6 GB 사용 관측).
6. Staging·Prod 배포가 불가한 이유
Dev는 원래 Linux 전용 단계가 적었고 맞지 않던 세 군데를 고쳐 이 PC에서 돌게 했다. Staging·Prod 워크플로에는 이 수정이 없고 macOS에서 돌 수 없는 단계가 있다.
| 조건 | Dev | Staging / Prod |
|---|---|---|
| runner 선택 | runner 입력으로 선택 | web(deploy-staging-web.yml, deploy-prod-web.yml), socket, audio-analysis, recorder, livekit-agent가 모두 runs-on: self-hosted 고정. 이 PC에는 self-hosted 라벨이 없어 job이 오지 않는다 |
| Linux 전용 action | 없음 | Staging web 헬스 체크가 appleboy/ssh-action(Docker container action)을 쓴다. GitHub는 container action을 Linux runner에서만 실행한다 |
| Linux 전용 명령 | gh 설치를 macOS 지원으로 수정 | Staging·Prod web HA 경로가 sudo dnf install로 session-manager-plugin을 설치한다(Amazon Linux 전용) |
| 이미지 아키텍처 | linux/arm64만 빌드 | LiveKit Agent가 linux/amd64. arm64 Mac에서는 에뮬레이션이 필요해 느리고 RAM 8 GB로는 메모리 부족 위험이 크다 |
| Docker·gh 설정 | macOS 대응 반영 | 각 워크플로와 action에 같은 수정을 따로 해야 한다 |
| AWS 인증 | OIDC 단기 자격 증명만 사용 | 일부 단계가 장기 AWS 키(AWS_ACCESS_KEY_ID)와 EC2 SSH 키를 사용한다 |
| 대상 환경 | 브랜치 전용 환경을 만들었다 지운다. 실패해도 다른 사람에게 영향이 없다 | 운영 중인 공용 환경을 직접 교체한다. Prod audio-analysis는 environment: production 승인 절차를 거친다 |
코드를 고치면 기술적으로는 가능할 수 있다. 하지만 사무실 데스크톱 상시 runner가 운영 비밀값을 다루게 되고, 이 PC는 메모리가 빠듯하며 공유기 DNS가 일시적으로 실패한 적이 있다. Staging·Prod는 기존 Linux self-hosted runner를 유지한다. 빌드 시간 단축이 목적이면 이미지 빌드만 이 PC에서 하고 배포는 Linux runner가 하도록 job을 나누는 방안을 별도로 설계한다.
7. 멈춘 지점을 확인한다
- Queued에서 멈춤:
runner=ppi-local-build를 골랐는지, runner 목록에서ppi-local-build-pc가 Idle인지 확인한다. Unsupported GitHub CLI runner platform:feature/local-build가 아닌 브랜치에서 실행했다. macOS 지원은 이 브랜치에만 있다.Docker Desktop CLI plugins or socket is unavailable: Docker Desktop이 꺼져 있다. Settings → General의 Start Docker Desktop when you sign in을 켜 두면 재부팅 후에도 자동으로 뜬다.cannot allocate memory,Killed: Docker VM 메모리와 Swap 설정을 확인하고 빌드 중 다른 무거운 작업을 피한다.Terraform plan failed; diagnostics saved only in the protected state bucket: 공개 로그에는 원인이 남지 않고 runner 사본도 job 끝에서 지워진다. AWS SSO 프로필(역할PpiDeveloper, 리전ap-northeast-2)로 state 버킷의 로그를 읽는다. SSO 설정 값은 AWS SSO PpiDiagnostics 프로필 설정 가이드와 사내 Session Manager Plugin 가이드를 따른다.- plan 로그의
lookup …amazonaws.com: no such host: 공유기 DNS의 일시 장애다. 재실행하면 통과한다. 반복되면 공용 DNS 지정을 검토한다(sudo networksetup -setdnsservers Ethernet 1.1.1.1 8.8.8.8, 사내 도메인 영향 확인 후).
aws sso login --profile ppi-dev
aws s3 cp --profile ppi-dev \
"s3://ppi-terraform-state/ppi-dev-reviewed-plans/feature-local-build/<RUN_ID>/failed-plan.log" - \
| grep -nE "^Error|Error:|lock"
plan 로그에는 민감한 값이 있을 수 있다. 파일로 내려받았다면 확인 후 지운다.
근거와 검증 범위
- PPI
feature/local-build커밋84bc91fa의.github/workflows/dev.yml,scripts/setup-dev-gh.sh와 테스트 2개. 로컬에서 새 테스트 21건 통과, dev.yml을 읽는 기존 테스트의 실패 목록은 변경 전과 동일했다. - 이 PC에서
setup-dev-gh.sh를 실제 실행해 gh 2.102.0 macOS 설치와 체크섬 검증을 확인했다. Docker 설정 단계를 실제 실행해 수정 전 실패와 수정 후 buildx v0.38.1·Docker 29.9.3(arm64) 연결을 확인했다. - GitHub Actions run 44238383191, 44239901798, 44244026986의 단계 결과와 로그, 두 번째 run의 state 버킷 plan 로그.
- Staging·Prod 판단은
deploy-staging.yml,deploy-staging-web.yml,deploy-web-prod.yml,deploy-prod-web.yml, recorder·audio-analysis·livekit-agent 워크플로와 action의 정적 확인 결과다. 이 PC에서 Staging·Prod 배포를 실행하지 않았다.
관련 PPI 문서
- 로컬 self-hosted runner로 PPI 빌드 실험하기: runner 등록, 전용 라벨, 빌드 실험 workflow.
- Staging · Dev 배포 시간 분석: 기존 runner에서 오래 걸린 단계와 개선 후보.
- PPI Web 코드 수정 때 빌드가 오래 걸리는 이유와 개선안: 캐시 적중에 따른 빌드 시간 차이.
- PPI 배포 빌드 시간 단축 방법: 로컬 runner에서 builder를 유지해
.next/cache를 재사용하는 실험 후보.