빌드 실험 실행 가이드 · 2026-11-17

로컬 self-hosted runner로
PPI 빌드 실험하기

마지막 업데이트 2026-11-17

대상: 빌드 시간을 줄이기 위해 Containerfile과 workflow를 반복 수정하는 개발자

로컬 PC에 빌드 전용 runner를 등록하고, 실험 브랜치의 job만 실행한다. 기본 self-hosted 라벨은 등록하지 않는다. PPI의 기존 배포 job이 이 PC를 선택하는 것을 막기 위해서다.

이 문서는 실행 절차와 예제를 제공한다. runner 설치, PPI workflow 변경, 실제 이미지 빌드 및 성능 측정은 이 문서 작성 과정에서 수행하지 않았다.

1. PC와 Docker 실행 환경을 준비한다

  1. Mac에서는 Docker Desktop 또는 이미 사용하는 Docker 환경을 시작한다. Linux에서는 Docker Engine을 시작한다.
  2. runner를 실행할 일반 사용자 계정에서 아래 명령을 확인한다. Docker daemon에 접근할 수 있어야 한다.
git --version
docker version
docker buildx version
uname -m

docker version에 Client와 Server가 모두 보여야 한다. Apple Silicon의 arm64 또는 aarch64는 linux/arm64, Intel의 x86_64는 linux/amd64 빌드부터 실험한다.

아래 예제는 checkout과 shell 명령으로 Docker를 호출하므로 Mac에서 실행할 수 있다. 기존 배포 workflow 전체에는 Linux 전용 설치 명령과 Docker container action이 있어 별도 호환성 검토가 필요하다. container action과 service container는 Linux runner에서 실행한다.

PC에서 GitHub로 나가는 HTTPS 443 통신과 이미지·패키지 다운로드 경로가 열려 있어야 한다. runner 수신용 포트 포워딩은 필요하지 않다. 개인 작업 계정과 분리된 계정 또는 VM을 사용하고, 신뢰하는 실험 브랜치만 실행한다.

2. 기본 라벨 없이 runner를 등록한다

  1. PPI 저장소의 Settings → Actions → Runners에서 New self-hosted runner를 연다. 메뉴가 없거나 등록이 금지돼 있으면 저장소 관리자에게 등록 권한과 조직 정책을 확인한다.
  2. 실제 runner 프로세스가 실행될 OS와 아키텍처를 선택한다. Mac에서 Linux 이미지를 빌드하더라도 runner 프로세스가 Mac에서 실행되면 macOS를 고른다. Linux VM 안에 설치하면 Linux를 고른다.
  3. 소스 checkout과 분리된 디렉터리를 만들고 이동한다.
mkdir -p "$HOME/actions-runner-ppi-build"
cd "$HOME/actions-runner-ppi-build"

GitHub 화면의 Download 명령을 이 디렉터리에서 실행한다. 화면에 제공된 다운로드, SHA-256 검증, 압축 해제 명령을 그대로 사용한다. 버전과 체크섬은 이 문서에 고정하지 않는다.

화면의 Configure 명령 대신 아래 명령에 새 등록 토큰을 넣어 실행한다. 등록 토큰은 1시간 뒤 만료되므로, 만료되면 화면에서 새 토큰을 발급받는다. 토큰을 문서나 Git에 저장하지 않는다.

./config.sh \
  --url https://github.com/Dobraindev/ppi \
  --token '<GitHub 화면의 등록 토큰>' \
  --name ppi-local-build-pc \
  --no-default-labels \
  --labels ppi-local-build \
  --work _work

등록 후 GitHub runner 목록에서 ppi-local-build 라벨이 있고 self-hosted 라벨이 없는지 확인한다. 실행 전에는 Offline, 실행 후에는 Idle로 표시된다.

전용 라벨 추가만으로는 격리되지 않는다. 기본 self-hosted 라벨을 유지하면 현재 PPI의 runs-on: self-hosted 배포 job도 이 PC에 배정될 수 있다. concurrency.group은 runner group이 아니라 동시 실행 제어 이름이다. 실험 job은 runs-on: ppi-local-build로 지정한다. 전용 라벨도 접근 권한 경계는 아니므로 신뢰하지 않는 코드는 실행하지 않는다.

3. builder를 만들고 runner를 실행한다

runner를 실행할 같은 사용자 계정에서 전용 builder를 한 번 만든다. 이미 존재하면 생성 명령을 건너뛰고 inspect부터 실행한다.

docker buildx create --name ppi-local-build --driver docker-container
docker buildx inspect ppi-local-build --bootstrap

이 builder를 반복 사용하면 BuildKit 내부 캐시와 Containerfile의 패키지 cache mount를 재사용할 수 있다. 실험 중에는 builder를 삭제하거나 전체 Docker 캐시를 정리하지 않는다.

등록 디렉터리에서 runner를 시작한다. Mac에서는 작업 중 자동 유휴 절전을 막기 위해 다음 명령을 사용한다. 노트북 덮개를 닫으면 별도 절전 조건이 적용될 수 있으므로 열어 둔다.

cd "$HOME/actions-runner-ppi-build"
caffeinate -i ./run.sh

Linux에서는 같은 디렉터리에서 ./run.sh를 실행한다. Listening for Jobs가 출력되고 GitHub 목록이 Idle이 되면 준비가 끝난다. 처음에는 foreground로 실행해 로그를 확인한다.

4. 빌드 전용 workflow를 실험 브랜치에 추가한다

PPI 저장소의 .github/workflows/local-build-experiment.yml에 아래 예제를 저장한다. 이 파일은 제안 예제이며 현재 PPI에 설치돼 있지 않다.

기존 작업과 분리된 experiment/local-build/첫실험 형태의 브랜치를 사용한다. 기존 배포 workflow의 트리거도 먼저 확인한다. 아래 workflow는 해당 브랜치에 push할 때 실행되므로, 최초 실행을 위해 기본 브랜치에 병합할 필요가 없다.

name: Local build experiment

on:
  push:
    branches:
      - 'experiment/local-build/**'

permissions:
  contents: read

concurrency:
  group: ppi-local-build
  cancel-in-progress: false

jobs:
  build:
    runs-on: ppi-local-build
    timeout-minutes: 60
    defaults:
      run:
        shell: bash
    env:
      # Apple Silicon 예제. Intel에서는 linux/amd64로 변경한다.
      BUILD_PLATFORM: linux/arm64
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Check Docker builder
        run: |
          set -euo pipefail
          docker version
          docker buildx inspect ppi-local-build --bootstrap

      - name: Build web image to local OCI archive
        run: |
          set -euo pipefail
          time docker buildx build \
            --builder ppi-local-build \
            --platform "$BUILD_PLATFORM" \
            --progress=plain \
            --build-arg GIT_SHA="$GITHUB_SHA" \
            --build-arg NEXT_PUBLIC_LOGROCKET_ENV=local-benchmark \
            --build-arg NEXT_PUBLIC_API_BASE_URL=https://ppistg.dubuhealth.in \
            --build-arg NEXT_PUBLIC_AUDIO_ANALYSIS_PCM_CAPTURE=true \
            --output "type=oci,dest=$RUNNER_TEMP/ppi-web-local.tar" \
            -f apps/web/Containerfile .

      - name: Remove experiment archive
        if: always()
        run: rm -f -- "$RUNNER_TEMP/ppi-web-local.tar"

예제는 최종 이미지 생성과 OCI 파일 출력을 포함한다. GHCR push, AWS 인증, 서버 배포는 수행하지 않는다. 패키지·이미지 다운로드와 빌드 코드의 네트워크 접근은 발생할 수 있다. 기본 빌드 실험에는 AWS 키나 GHCR 토큰이 필요하지 않다.

NEXT_PUBLIC_* 값은 실험용이다. 현재 Containerfile은 SERVER_ACTIONS_KEY_REFERENCE가 비어 있으면 secret 없이 빌드하는 경로를 허용한다. 이 이미지는 배포용으로 사용하지 않는다. 배포 workflow의 키 조회·secret mount·인증 경로는 별도로 검증한다.

  1. 예제 파일을 실험 브랜치에 commit하고 push한다.
  2. GitHub Actions에서 Local build experiment 실행을 연다.
  3. job에 배정된 runner가 ppi-local-build-pc인지 확인한다.
  4. 빌드 단계가 성공하고 다음 실행에서 변경하지 않은 단계에 CACHED가 나타나는지 확인한다.

수동 실행이 필요하면 workflow_dispatch를 추가한다. 이 이벤트는 workflow 파일이 기본 브랜치에 존재해야 사용할 수 있으므로, 새 실험 브랜치에 파일만 올린 상태에서는 위 push 트리거를 사용한다.

5. 수정 범위에 맞춰 반복 실행한다

workflow YAML, Actions 인증, job 연결을 바꾸면 commit과 push로 확인한다. 로컬 runner도 GitHub가 할당한 job을 실행하므로 미커밋 workflow를 자동으로 읽지 않는다.

Containerfile과 빌드 옵션만 실험할 때는 별도 터미널의 PPI 개발 checkout에서 직접 실행한다. runner의 _work 디렉터리는 수정하지 않는다. runner job이 끝난 뒤 같은 builder로 아래 명령을 실행한다.

# PPI 개발 checkout 루트에서 실행한다. Apple Silicon 예제다.
time docker buildx build \
  --builder ppi-local-build \
  --platform linux/arm64 \
  --progress=plain \
  --build-arg GIT_SHA="$(git rev-parse HEAD)" \
  --build-arg NEXT_PUBLIC_LOGROCKET_ENV=local-benchmark \
  --build-arg NEXT_PUBLIC_API_BASE_URL=https://ppistg.dubuhealth.in \
  --build-arg NEXT_PUBLIC_AUDIO_ANALYSIS_PCM_CAPTURE=true \
  --output type=oci,dest=/tmp/ppi-web-local.tar \
  -f apps/web/Containerfile .

현재 checkout의 수정 내용으로 빌드한다. 로컬 직접 실행과 runner job은 함께 돌리지 않는다. 비교 후 생성한 /tmp/ppi-web-local.tar 파일을 삭제해 디스크 공간을 회수한다. Next.js 빌드까지만 좁혀 볼 때는 --target builder를 추가하고 OCI 출력 옵션을 뺀다. 이 경우 최종 runtime 이미지 생성과 출력 시간은 측정에서 제외된다.

빌드 명령을 스크립트로 공통화하면 로컬과 Actions의 명령 차이를 줄일 수 있다. 스크립트 추가는 후속 코드 변경이며 이 문서에서는 수행하지 않는다.

6. 같은 조건에서 개선 전후를 비교한다

  1. 기존 배포 runner의 CPU 아키텍처와 builder 설정을 먼저 기록한다. 이 문서에서는 실제 runner의 아키텍처를 조회하지 않았다.
  2. 기준 커밋, 변경 커밋, 빌드 인자, Docker에 할당한 CPU와 메모리, 플랫폼, 출력 방식을 함께 기록한다.
  3. 첫 빌드와 캐시가 있는 반복 빌드를 나눠 기록한다. 변경이 없는 재실행 외에 실제 소스 한 파일을 바꾼 재빌드도 비교한다.
  4. --progress=plain 로그에서 패키지 설치, Next.js 빌드, 이미지 출력 시간을 구분한다. time의 전체 경과 시간과 Actions 대기 시간도 나눠 본다.
  5. 개선 후보를 정하면 기존 배포 runner에서 같은 조건으로 최종 비교한다. 배포의 GHCR 업로드와 registry 캐시 가져오기·내보내기 시간까지 확인한다.

로컬 builder의 내부 캐시와 레지스트리 캐시는 별개다. 현재 staging web workflow는 GHCR buildcache에 --cache-from과 --cache-to를 사용하고, 위 예제는 로컬 캐시만 사용한다. 실험용 registry 캐시가 필요하면 기존 배포 캐시와 다른 ref에 쓴다.

--no-cache만으로 cache mount의 패키지 저장소까지 초기화되지는 않는다. 완전히 새 builder가 필요한 비교라면 별도 이름으로 생성한다. Apple Silicon에서 linux/amd64를 에뮬레이션하면 컴파일 시간이 늘어날 수 있다. 로컬 실행 시간만으로 배포 runner의 절감량을 확정하지 않는다.

7. runner를 중지하거나 제거한다

새 job이 들어오지 않게 실험 push를 멈춘다. 실행 중인 job이 끝난 뒤 runner 터미널에서 Ctrl+C를 누른다. GitHub runner 목록이 Offline으로 바뀐다. 다음 실험 때 같은 디렉터리에서 다시 실행하면 된다.

등록을 완전히 제거하려면 GitHub의 runner 상세 화면에서 Remove를 열고, 화면에 제공된 새 제거 토큰으로 등록 디렉터리에서 실행한다.

./config.sh remove --token '<GitHub 화면의 제거 토큰>'

실험이 끝나 캐시도 필요 없으면 아래 명령으로 전용 builder를 제거한다. 다른 프로젝트가 사용하는 builder와 이미지는 정리하지 않는다.

docker buildx rm ppi-local-build

8. 멈춘 지점을 확인한다

근거와 검증 범위

2026-11-17 PPI release/3.23.0 작업트리의 9e6e3c06 기준으로 다음 설정을 읽고 작성했다.

검증한 범위는 저장소 설정과 공식 사용법의 대조, 문서 링크·예제 구문 및 렌더링이다. 실제 runner 등록·빌드 성공·성능 개선은 미검증이며 사용자가 위 절차를 실행한 결과로 확인해야 한다.

관련 PPI 문서

공식 실행 절차