배포 실행 가이드 · 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 환경을 확인한다

항목값
하드웨어·OSMac 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)
DockerDocker 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 fromfeature/local-build
Action to performdeploy 또는 destroy
runnerppi-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-beginGitHub hosted브랜치 배포 lock 획득, 소유자 확인
deploy이 PCgh·Terraform 설치, web·socket 이미지 linux/arm64 빌드와 GHCR push, OIDC로 Dev AWS 인증, Terraform plan·apply, 앱 헬스 체크
destroy이 PCTerraform destroy와 남은 리소스 정리
lifecycle-finishGitHub hosted결과 기록, lock 해제

Dev OIDC 역할의 신뢰 조건은 저장소와 브랜치(repo:Dobraindev/ppi:ref:refs/heads/*)만 확인하므로 실행한 runner와 관계없이 인증된다. Dev EC2(t4g)와 이 PC가 모두 arm64라 에뮬레이션 없이 빌드한다.

4. feature/local-build에서 바꾼 것

커밋 84bc91fa "ci: Dev 배포를 로컬 macOS 빌드 러너에서 실행할 수 있게 한다".

  1. runner 선택: dev.yml에 runner 입력(self-hosted 기본, ppi-local-build)을 추가하고 deploy·destroy job을 runs-on: ${{ inputs.runner || 'self-hosted' }}로 바꿨다. 기본값이 그대로라 기존 실행에는 영향이 없다.
  2. gh 설치: scripts/setup-dev-gh.sh가 Linux만 허용하던 것을 macOS ARM64용 gh 2.102.0 zip도 받도록 했다. 체크섬은 공식 checksums 파일 값으로 고정했다. macOS의 sha256sum은 --check --status를 지원하지 않아 shasum -a 256을 쓴다.
  3. 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을 지정한다. 둘 중 하나가 없으면 빌드 전에 오류로 멈춘다.
  4. 테스트: 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에서 돌 수 없는 단계가 있다.

조건DevStaging / 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. 멈춘 지점을 확인한다

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 문서