셀프 호스팅 러너

셀프 호스팅 러너는 Subaya 빌드를 Subaya 클라우드가 아닌 직접 관리하는 머신에서 실행하는 작은 에이전트 subaya-runner입니다. 해당 머신에 툴체인이 이미 설치되어 있을 때(예: 라이선스가 있는 Quartus 설치) 또는 빌드를 자체 하드웨어에서 수행해야 할 때 사용하세요.

러너는 보안 WebSocket을 통해 Subaya로 아웃바운드 연결합니다. 인바운드 포트, VPN, 공인 IP가 필요하지 않습니다. Subaya는 이 연결을 통해 러너에 빌드를 보냅니다.

러너는 자신의 조직을 위한 빌드를, 플랫폼이 그 조직의 프로젝트에서 도출한 명령으로 실행합니다. 빌드는 사용자가 소유한 머신에서 러너의 권한으로 실행됩니다 — GitHub 셀프 호스팅 러너와 동일한 신뢰 모델입니다. 샌드박스가 아닙니다.

요구 사항

• x86_64 기반 Linux. 다른 플랫폼은 추후 지원됩니다.
• subaya-dev.com으로의 아웃바운드 HTTPS(포트 443).
• 빌드에 필요한 도구가 설치되어 있고, 러너를 실행하는 사용자의 PATH에 있어야 합니다. 러너는 찾은 것을 보고할 뿐 아무것도 설치하지 않습니다.
• 선택 사항: 레시피가 컨테이너 이미지를 지정하는 빌드를 위한 Docker 또는 Podman.

설치

콘솔에서 Settings → Runners를 열고 Add runner를 선택합니다. 러너에 이름을 지정하면 Subaya가 일회용 등록 토큰이 이미 채워진 세 가지 명령을 보여 줍니다. 토큰은 한 번만 사용할 수 있으며 1시간 후 만료됩니다.

러너를 다운로드하고 압축을 풉니다:

curl -fsSL -o subaya-runner.tar.gz https://subaya-dev.com/cli/runner/latest/subaya-runner_linux_amd64.tar.gz && tar xzf subaya-runner.tar.gz

러너를 구성합니다. 이 단계에서 등록 토큰이 러너 자체의 자격 증명으로 교환되고, 머신을 절대 벗어나지 않는 키 쌍이 생성됩니다:

./subaya-runner configure --url https://subaya-dev.com --token srt_... --name 'lab-quartus-01'

포그라운드에서 실행합니다:

./subaya-runner run

재부팅 후에도 계속 실행되게 하려면 대신 systemd 서비스로 설치합니다:

./subaya-runner install-service

내 사용자로 실행하면 systemd 사용자 서비스로, root로 실행하면 시스템 전체 서비스로 설치됩니다. 사용자 서비스는 계정에 lingering을 활성화하지 않으면 로그아웃할 때 중지됩니다:

sudo loginctl enable-linger "$USER"

몇 초 안에 러너가 감지한 도구 및 버전과 함께 Settings → Runners에 online으로 표시됩니다.

러너로 빌드 보내기

--runner로 이름을 지정해 러너를 대상으로 합니다:

suya build <app> --source . --runner lab-quartus-01 --wait

Subaya는 빌드를 수락하기 전에 빌드에 필요한 모든 도구를 러너가 보고했는지 확인합니다. 러너가 오프라인이면 빌드는 대기열에서 기다리다가 러너가 다시 연결되면 시작됩니다.

기록되는 내용

빌드가 시작되면 러너는 측정한 정확한 툴체인을 보고합니다: 각 도구의 버전 문자열, 경로, 바이너리의 SHA-256입니다. 실행에 기록되는 것은 프로젝트가 요청한 것이 아니라 이 측정된 툴체인입니다.

프로젝트가 도구 버전을 명시적으로 고정했고(예: suya tools set quartus-pro 26.1.1) 러너에 설치된 버전이 고정 버전과 일치하지 않으면, 빌드는 거부되고 toolchain_pin_mismatch로 실패합니다. 아무것도 실행되지 않습니다. 명시적 고정이 없으면 러너에 설치된 버전이 사용됩니다.

러너 폐기

Settings → Runners에서 해당 러너의 Revoke를 선택합니다. 폐기는 즉시 적용됩니다: 러너의 자격 증명이 더 이상 작동하지 않고, 연결이 종료되며, 더 이상 빌드가 전송되지 않고, 실행 중인 빌드는 실패합니다. 폐기는 되돌릴 수 없습니다 — 머신을 다시 사용하려면 새 러너로 추가하고 새 토큰으로 ./subaya-runner configure --replace를 실행하세요.

머신에서 서비스도 제거하려면:

./subaya-runner uninstall-service

문제 해결

러너가 오프라인으로 표시됩니다. 프로세스나 서비스가 실행 중인지, 그리고 머신이 포트 443으로 subaya-dev.com에 연결할 수 있는지 확인하세요:

./subaya-runner status

러너는 네트워크가 끊긴 후 스스로 다시 연결합니다. 연결이 끊겼을 때 실행 중이던 빌드는 runner_disconnected로 실패하므로 다시 실행하세요.

러너가 “upgrade required”로 종료됩니다. 러너가 Subaya가 허용하는 최소 버전보다 오래되었습니다. 위의 다운로드 명령으로 최신 릴리스를 받아 바이너리를 교체한 뒤 다시 시작하세요. 구성은 유지됩니다.

빌드가 422 runner_missing_tool로 거부됩니다. 빌드에 필요한 도구를 러너가 보고하지 않았습니다. 도구를 설치하고 러너의 PATH에 있는지 확인한 다음, 툴체인을 다시 보고하도록 러너를 재시작하세요. 오류 메시지에 누락된 도구가 표시됩니다.

등록 토큰이 거부됩니다. 토큰은 일회용이며 1시간 후 만료됩니다. Add runner로 새 토큰을 만드세요.

다음 단계

• 워크스페이스와 프로젝트 — 빌드가 존재하는 곳.
• 청구 및 사용량 — 클라우드 컴퓨팅이 측정되는 방식.