General Runner

Apidog Self-hosted Runner는 독립형 서버에 호스팅할 수 있는 자동화 프로그램으로 이해하실 수 있습니다. 예약된 자동화 테스트, 예약된 API 문서 가져오기, 목 응답 결과 반환과 같은 Apidog 내 작업을 실행할 수 있습니다.

준비

호스트 머신(서버 또는 로컬 PC)에 Docker가 설치되어 있어야 합니다.

필요한 최소 Docker 버전은 20.10.0이며, 20.10.13 버전을 권장합니다.

빠른 시작

이 섹션에서는 서버에 General Runner를 배포하는 방법을 안내합니다.

1. General Runner 배포

Apidog Home 페이지로 이동하여 원하는 팀을 선택한 다음, 오른쪽의 Resources를 클릭합니다. 이후 Deploy General Runner를 클릭하여 시작합니다.

2. Runner 배포 명령 가져오기

Deploy General Runner를 클릭하면 팝업 창에서 General Runner의 배포 명령을 복사합니다. 필요에 따라 명령을 사용자 지정할 수 있으며, 사용자 지정 서버 OS, 노출 포트, 데이터 디렉터리 마운트 등을 지원합니다. 아래는 이러한 설정에 대한 자세한 설명입니다.

Server OS: Docker 컨테이너의 운영 체제를 지정합니다. 여기에는 Linux, macOS, Windows가 포함됩니다. 올바른 운영 체제를 선택하는 것은 Docker 컨테이너가 정상적으로 작동하도록 보장하는 데 중요합니다.

Docker Image: General, Slim, Custom 세 가지 버전을 사용할 수 있습니다. "custom script"가 외부 프로그램을 호출해야 하는 경우, 필요한 환경에 따라 설치할 적절한 이미지를 선택하십시오.

General: Runner의 모든 기능을 포함하며, 다음 언어 환경이 사전 설치되어 있습니다: Node.js 18, Java 21, Python 3, PHP 8.

Slim: Runner의 모든 기능을 포함하지만 Node.js 18만 사전 설치되어 있습니다.

Custom: Runner의 모든 기능을 포함하며, 외부 프로그램을 위한 사용자 지정 언어 환경을 지원합니다. 필요에 따라 환경을 추가하거나 제거하기 위해 직접 Dockerfile을 생성할 수 있습니다.

Exposed Port: 기본적으로 Docker 컨테이너는 외부 접근을 위해 내부 포트를 노출하지 않습니다. -p 매개변수를 사용하면 컨테이너의 내부 포트를 호스트 머신의 포트에 매핑하여, 컨테이너에서 제공하는 서비스에 외부에서 접근할 수 있습니다. 예를 들어 -p 80:4524는 컨테이너의 내부 포트 4524를 호스트 머신의 포트 80에 매핑합니다.

Mount Data Directory: -v 매개변수를 사용하면 호스트 머신의 디렉터리를 컨테이너에 마운트하여, 컨테이너가 호스트의 파일(예: 데이터베이스 구성 또는 외부 프로그램)에 접근하고 조작할 수 있습니다. 예를 들어 -v "/opt/runner":/opt/runner는 호스트의 /opt/runner 디렉터리를 컨테이너의 /opt/runner 디렉터리에 마운트합니다.

TIP

배포 명령에는 토큰 정보가 포함되어 있으며, 데이터 보안상의 이유로 한 번만 표시됩니다. Deploy General Runner를 클릭할 때마다 새 명령이 생성됩니다.

향후 Runner 업그레이드에 사용할 수 있으므로, 명령을 로컬에 저장해 주십시오.

3. 서버에 Runner 배포

복사한 배포 명령을 서버의 터미널에 붙여넣으면 Runner 설치가 자동으로 시작됩니다.

TIP

Runner의 배포 속성을 환경 변수를 통해 수정하여 실제 사용 시나리오에 더 잘 맞출 수 있습니다. 자세한 내용은 runner deployment environment를 참조하십시오.

설치가 완료되면 터미널에 관련 정보가 출력됩니다. 오류가 있는 경우 오류 세부 정보를 바탕으로 문제를 해결할 수 있습니다. 그래도 해결할 수 없다면 contact us로 문의하시고 피드백을 제공해 주십시오.

4. 서버에서 Runner 상태 보기

Docker 클라이언트를 통해 컨테이너의 실행 상태를 확인할 수 있습니다.

터미널에서 docker ps 명령을 사용하여 컨테이너의 실행 상태를 확인할 수도 있습니다.

5. Apidog에서 배포된 General Runner 보기

서버의 Runner 컨테이너가 배포 및 활성화되었음을 확인한 후 Apidog로 돌아갑니다. Team Resources → General Runner에서 Runner가 배포되어 Apidog에 연결된 것을 확인할 수 있습니다.

General Runner가 서버에 성공적으로 배포되었지만 Apidog 클라이언트에 표시되지 않는 경우, "General Runner" 오른쪽에 있는 새로고침 버튼을 클릭하여 페이지를 새로고침한 뒤 다시 확인해 주십시오.

팀 구성원이 이 Runner를 더 잘 사용할 수 있도록 Runner의 이름을 변경하고, 설명을 추가하고, 삭제할 수 있습니다. 또한 Runner를 중지/재시작할 수도 있습니다.

일시 중지된 Runner는 더 이상 지정된 예약 작업을 실행하지 않으며, 새 관련 작업을 생성하여 이 Runner가 실행하도록 지정할 수도 없습니다.

Runner의 상태 설명은 아래 표를 참조하십시오.

상태	설명
시작됨	Runner가 서버의 컨테이너에서 정상적으로 활성화되어 있으며, Apidog와의 통신을 유지하고 Apidog에서 발행한 관련 작업을 처리할 수 있습니다.
중지됨	Runner가 Apidog에서 수동으로 중지되었지만, 서버의 컨테이너에서는 정상적으로 계속 실행되며 통신을 유지합니다. Apidog에서 발행한 작업을 처리하지 않으며, 새 작업은 중지된 Runner를 실행 대상으로 지정할 수 없습니다. Apidog에서 수동으로 활성화하여 Runner를 시작됨 상태로 복원할 수 있습니다.
오프라인	Runner가 Apidog와의 연결이 끊어져 작업을 처리할 수 없습니다. 이는 서버에서 Runner 컨테이너가 중지되었거나 서버와 Apidog 간 통신 문제가 있기 때문일 수 있습니다. Runner를 복원하려면 Runner 컨테이너가 실행 중인지, Apidog와의 통신 문제가 없는지 확인하여 Runner가 시작됨 상태로 복원될 수 있도록 하십시오.

한 팀 내에 여러 General Runner를 배포할 수 있습니다. 셀프 호스팅 Runner가 필요한 작업을 생성할 때 팀 구성원은 사용 가능한 Runner 중에서 선택할 수 있습니다.

Runner에 파일 저장

Runner를 사용하여 엔드포인트 요청, 테스트 시나리오, 예약 작업과 같은 작업을 실행할 때, 작업 실행을 지원하기 위해 특정 로컬 파일이 필요할 수 있습니다. 예시는 다음과 같습니다.

사용자 지정 스크립트에서 다른 프로그래밍 언어 호출

Pre/Post Processors에서 데이터베이스 연결 사용

요청을 보낼 때 SSL 인증서 사용

이를 지원하려면 필요한 파일을 Docker 컨테이너 내 지정된 디렉터리에 저장하십시오. Runner가 관련 작업을 실행할 때, 작업 요구 사항에 따라 지정된 디렉터리에서 파일 내용을 읽어 성공적으로 완료되도록 합니다.

사용을 위해 적절한 형식과 내용의 파일을 지정된 디렉터리에 배치하려면 다음 표를 참조하십시오.

사용 내용	지정된 디렉터리 경로(또는 파일 이름)	Docker 명령 예시
Other Programming Languages	/app/external-programs/	-v /Users/xxx/runner/packages/api-test/external-programs:/app/externalPrograms
Database 연결 구성 파일	/app/database/database-connections.json	-v /Users/xxx/runner/packages/api-test/database/database-connections.json:/app/database/database-connections.json
SSL Certificate 목록 파일	/app/ssl/ssl-client-cert-list.json	-v /Users/xxx/runner/packages/api-test/ssl/ssl-client-cert-list.json:/app/ssl/ssl-client-cert-list.json

Apidog 클라이언트에서 구성 파일을 내보내는 방법은 This Page를 참조하실 수 있습니다.

Runner 업그레이드 및 재배포

Runner 업그레이드

Runner의 새 버전이 출시되면 데스크톱 Runner UI에 업그레이드 아이콘이 표시됩니다. 아이콘을 클릭하여 Apidog에서 제공하는 최신 버전을 설치하십시오.

Upgrade를 클릭하면 현재 실행 중인 Runner 컨테이너를 중지하라는 메시지가 표시됩니다. 컨테이너가 중지되면 예약 작업 및 클라이언트에서 이 Runner로 전송된 모든 작업이 더 이상 실행되지 않는다는 점에 유의하십시오.

업그레이드를 확인하면 Apidog가 현재 Runner 컨테이너를 자동으로 중지하고 새 버전을 배포하기 위한 명령을 제공합니다. Runner를 재배포하려면 초기 배포 단계를 따르십시오. 배포가 성공하면 최신 버전을 사용하게 됩니다. 참고: 클라이언트의 기존 예약 작업은 영향을 받지 않으며 다시 할당할 필요가 없습니다.

Runner 재배포

Runner에 문제가 발생했으며 Q&A 섹션에서 해결 방법을 찾을 수 없거나 안내가 도움이 되지 않는 경우, Runner 재배포를 고려하십시오. 이를 수행하려면 해당 Runner의 More Actions 섹션으로 이동하여 Redeploy를 클릭하십시오.

재배포 절차는 위의 업그레이드와 동일합니다. 참고: 재배포 시에도 Runner 컨테이너가 중지됩니다.

Q&A

1. 문제 진단을 위해 Runner 로그를 확인하는 방법은 무엇입니까?

docker ps 명령을 사용하여 문제가 있는 Runner를 찾으십시오.

다음 명령을 사용하여 로그를 확인하십시오.

Runner가 다운/연결 해제되었거나 작업을 실행할 수 없습니다. 어떻게 해야 합니까?

1단계: 문제 진단을 위한 정보를 수집하십시오.

오류 패턴 또는 운영 세부 정보를 확인하십시오.

개발자 도구(Alt+7+8)를 열고, 테스트 시나리오를 문제가 있는 Runner로 전송한 다음 엔드포인트 세부 정보를 기록하십시오.

Runner 로그를 검토하여 오류 메시지나 단서를 찾으십시오.

2단계: 문제를 해결하십시오.

문제를 식별할 수 있고 Apidog 버그로 인한 것이 아니라면 직접 수정하십시오.

문제를 정확히 파악할 수 없다면 추가 지원을 위해 Apidog 커뮤니티에 문의하십시오.

Runner가 예약 작업을 완료한 후 알림을 받지 못한 이유는 무엇입니까?

1단계: 작업 완료 여부를 확인하십시오.

예약 작업에 대한 테스트 보고서가 Apidog 클라이언트에서 제공되는지 확인하십시오.

Runner 로그를 검토하여 문제가 있는지 확인하십시오.

2단계: 알림 구성을 확인하십시오.

알림 설정이 예약 작업 내에 저장되어 있는지 확인하십시오.

조건과 수신자가 올바르게 구성되어 있는지 다시 확인하십시오.

알림이 정상적으로 전송되는지 확인하려면 작업을 수동으로 트리거해 보십시오.

'No Runner Privilege' 오류는 무엇을 의미하며 어떻게 해결합니까?

이 오류에는 두 가지 가능한 원인이 있습니다.

배포 명령이 다시 생성됨: 명령을 생성하고 팝업을 닫은 뒤 다시 클릭한 경우, 새 토큰이 이전 토큰을 무효화할 수 있습니다. 이를 해결하려면 다음을 수행하십시오.

왼쪽 상단 모서리에서 다른 팀으로 전환한 다음, Runner 배포가 필요한 팀으로 돌아오십시오.

배포 명령을 다시 생성하고 복사한 뒤 실행하십시오. 프로세스가 완료될 때까지 다시 생성하기 위해 클릭하지 않도록 하십시오.

teamId 변수의 ID 데이터 오류: 이는 최신 버전에서 수정된 알려진 버그입니다. 문제가 지속되는 경우 다음을 수행하십시오.

왼쪽 상단 모서리에서 다른 팀으로 전환한 다음, Runner 배포가 필요한 팀으로 돌아오십시오.

배포 명령을 다시 생성하고 복사한 뒤 실행하십시오. 프로세스가 완료될 때까지 다시 생성하기 위해 클릭하지 않도록 하십시오.

준비#

빠른 시작#

1. General Runner 배포#

2. Runner 배포 명령 가져오기#

3. 서버에 Runner 배포#

4. 서버에서 Runner 상태 보기#

5. Apidog에서 배포된 General Runner 보기#

Runner에 파일 저장#

Runner 업그레이드 및 재배포#

Runner 업그레이드#

Runner 재배포#

Q&A#

준비

빠른 시작

1. General Runner 배포

2. Runner 배포 명령 가져오기

3. 서버에 Runner 배포

4. 서버에서 Runner 상태 보기

5. Apidog에서 배포된 General Runner 보기

Runner에 파일 저장

Runner 업그레이드 및 재배포

Runner 업그레이드

Runner 재배포

Q&A