Apidog로 인트라넷에 자체 호스팅 목 서버 운영 방법

일부 팀은 트래픽을 클라우드로 보낼 수 없습니다. 기업 방화벽 뒤에 있어 서드파티 서비스로의 아웃바운드 호출이 차단될 수 있습니다. 규정 준수 규칙에 따라 요청 및 응답 데이터가 사용자가 제어하는 머신에 유지되어야 할 수도 있습니다. 전체 환경이 에어갭(air-gapped)되어 인트라넷 외부로 아무것도 나가지 못할 수도 있습니다. 이 모든 경우에, 심지어 모의 데이터 자체는 가짜일지라도 다른 사람의 인프라에 호스팅된 모의 URL은 시작조차 할 수 없습니다.

Apidog는 자체 호스팅 러너(self-hosted runner)로 이 문제를 해결합니다. 요청이 Apidog의 클라우드 모의로 나가는 대신, 사용자가 소유한 서버에 작은 프로그램을 배포하면 그 프로그램이 사용자 네트워크 내부에서 모의 응답을 반환합니다. 디자인은 항상 Apidog 프로젝트에 그대로 유지되며, 서비스만 사용자의 하드웨어로 이동합니다. 이 가이드에서는 러너가 무엇인지, 클라우드 모의 대신 러너를 선택해야 할 때, 문서에서 설정하는 방법, 그리고 사람들이 혼동하는 한 가지 차이점인 "러너는 CLI가 아니다"에 대해 설명합니다. 팀이 자체 서버에서 모의를 실행하는 이유에 대한 더 넓은 그림을 원하시면, 자체 호스팅 API 모의 서버에 대한 가이드가 일반적인 경우를 다루고 있으며, OpenAPI Initiative는 이 모의가 생성되는 사양을 설명합니다. 따라하고 싶으신가요? 먼저 Apidog를 다운로드하세요.

버튼

자체 호스팅 러너란 무엇인가요?

Apidog 자체 호스팅 러너는 독립 실행형 서버에 호스팅하는 자동화된 프로그램입니다. 공식적으로는 General Runner라고 불리며, 세 가지 작업을 수행합니다: 예약된 자동 테스트 실행, API 문서 가져오기, 모의 응답 반환. 이 세 번째 작업이 이 기사에서 다루는 내용입니다.

여기 핵심 아이디어가 있습니다. General Runner를 배포하고 서버 호스트를 설정하면, Runner Mock이라는 새 환경이 프로젝트에 자동으로 나타납니다. 해당 환경을 통해 전송하는 모든 요청은 Apidog의 클라우드 모의 대신 자체 호스팅 러너에서 모의 응답을 받습니다. 동일한 모의 디자인, 동일한 생성 데이터, 하지만 서비스를 제공하는 머신만 다릅니다. 귀하의 트래픽은 네트워크를 벗어나지 않습니다.

이는 클라우드 모의에 대한 자체 호스팅 대안입니다. 귀하의 팀이 인터넷에 연결할 수 있고 이에 대한 규칙이 없다면, Apidog 클라우드 모의는 배포할 것이 없으므로 더 간단합니다. 다음 중 하나에 해당할 때 러너를 사용하세요:

외부 호스트로의 아웃바운드 트래픽이 차단되거나 엄격하게 감사됩니다.
규정 준수 정책에 따라 요청 데이터가 내부 인프라에 유지되어야 합니다.
환경이 에어갭(air-gapped)되어 클라우드 엔드포인트에 전혀 연결할 수 없습니다.
공용 인터넷이 아닌 자체 LAN에서 모의 지연 시간을 측정하고 싶습니다.

이 중 아무것도 해당하지 않는다면, 추가적인 Docker 호스트는 불필요한 오버헤드입니다. 서버를 프로비저닝하기 전에 어떤 상황인지 스스로에게 솔직해지십시오.

요금제 및 권한에 대한 참고 사항입니다. Apidog 문서는 General Runner 또는 자체 호스팅 모의에 대한 무료-유료 구분이나 가격 책정 정보를 명시하지 않으므로, 이 가이드에서는 어떠한 정보도 생성하지 않습니다. 설정에는 팀 또는 프로젝트 관리자 권한이 필요합니다. 러너 배포는 팀 리소스 내에서 이루어지며, 관리자만 해당 설정을 열 수 있기 때문입니다. 리소스 패널이 보이지 않는다면, 그것이 이유입니다.

시작하기 전에 필요한 것

러너는 Docker 컨테이너로 제공되므로, 러너를 호스팅하는 서버에는 Docker가 설치되어 있어야 합니다. 문서에서는 최소 버전 20.10.0을 요구하며, 20.10.13 이상을 권장합니다. 현재 버전을 확인하려면 다음을 입력하세요:

docker --version

또한 실행할 장소도 필요합니다. 팀의 Apidog 클라이언트와 Apidog 서비스 모두에 연결할 수 있는 Linux, macOS 또는 Windows 머신입니다. 인트라넷에서는 일반적으로 안정적인 IP 또는 호스트 이름을 가진 내부 서버를 의미합니다. 이것이 전체 필수 조건 목록입니다: Docker, 호스트, 그리고 팀에 대한 관리자 권한. 그 외의 모든 것은 Apidog 자체 내에서 구성합니다.

General Runner 배포

배포 명령은 Apidog 내에서 자동으로 생성되며 토큰을 포함하므로, 직접 작성할 필요가 없습니다. 다음은 그 흐름입니다.

명령 생성

Apidog 홈을 열고 팀을 선택한 다음, 오른쪽 사이드바에서 리소스(Resources)를 클릭하고 General Runner 배포(Deploy General Runner)를 선택합니다. 몇 가지를 설정하는 팝업이 나타납니다:

서버 OS: Linux, macOS 또는 Windows. 생성된 명령이 호스트와 일치하도록 합니다.
Docker 이미지: General, Slim 또는 Custom을 선택합니다. General은 Node.js 18, Java 21, Python 3, PHP 8이 사전 설치되어 제공됩니다. Slim은 더 작은 이미지를 위해 Node.js 18만 제공합니다. Custom을 사용하면 테스트 스크립트에 추가 런타임이 필요할 때 자체 Dockerfile을 제공할 수 있습니다.
노출 포트(Exposed Port): 예를 들어 -p 80:4524와 같이 -p 매개변수로 설정하여 호스트 포트 80을 러너의 내부 포트에 매핑합니다.
마운트된 데이터 디렉토리(Mounted Data Directory): -v 매개변수로 설정하여 러너 데이터가 재시작 후에도 호스트에 유지되도록 합니다.

완료되면 생성된 명령을 복사합니다. 이것이 중요합니다: 명령은 토큰이 포함되어 있으므로 데이터 보안상의 이유로 한 번만 표시됩니다. 잃어버린 경우, 이전 것을 복구하는 대신 새 것을 생성해야 합니다. 즉시 캡처하십시오.

서버에서 실행

명령을 서버 터미널에 붙여넣으세요. 설치가 자동으로 시작되고 이미지를 가져옵니다. 완성된 명령은 대략 다음과 같습니다 (사용자의 것은 다를 것이고, 실제 토큰이 포함될 것입니다):

docker run -d \
  --name apidog-runner \
  -p 80:4524 \
  -v /opt/apidog-runner/data:/app/data \
  apidog/runner:latest \
  --token <YOUR_GENERATED_TOKEN>

컨테이너가 실행 중인지 확인하세요:

docker ps

러너 컨테이너가 포트 매핑과 함께 나열되어야 합니다. Docker Desktop과 같은 Docker 클라이언트도 UI에서 확인하고 싶다면 동일한 정보를 보여줍니다.

등록 확인

Apidog로 돌아가 팀 리소스(Team Resources)로 이동하여 General Runner를 엽니다. 새로고침 버튼을 클릭합니다. 러너는 이제 "시작됨(Started)" 상태로 배포된 것으로 표시되어야 합니다. 처음에는 나타나지 않을 수 있으므로, 새로고침 버튼을 클릭하고 잠시 기다린 후 다시 클릭하십시오.

러너 상태에는 알아야 할 세 가지 상태가 있습니다:

시작됨(Started): 활성화되어 Apidog와 통신하며 작업을 처리합니다. 이것이 원하는 상태입니다.
중지됨(Stopped): Apidog에서 누군가 수동으로 중지했습니다. 배포된 상태를 유지하지만 작업을 처리하지 않습니다.
오프라인(Offline): Apidog와의 연결이 끊어져 아무것도 처리할 수 없습니다. 컨테이너와 네트워크 경로를 확인하십시오.

러너 모의 켜기

러너를 배포하면 에이전트가 제공됩니다. 이제 모의 트래픽을 러너로 향하게 하는 한 단계만 더 남았습니다.

팀 리소스(Team Resources)에서 General Runner를 열고 서버 호스트(Server Host) 필드를 찾습니다. 러너에 접근할 수 있는 주소를 입력합니다. 일반적인 HTTP 설정에서는 로컬 테스트의 경우 http://127.0.0.1:80, 공유 인트라넷 호스트의 경우 http://runner.internal.example.com:80와 같이 호스트와 노출된 포트가 됩니다. TLS 종료 프록시 뒤에서는 https://runner.example.com:443와 같이 보입니다. HTTPS에 대해서는 잠시 후에 더 설명합니다.

서버 호스트가 설정되면 Apidog는 프로젝트에 대한 Runner Mock 환경을 자동으로 연결합니다. 프로젝트를 열고 환경 관리(Environment Management)로 이동하여 Runner Mock이 이제 환경 목록에 표시되는지 확인하십시오. 수동으로 생성한 것이 아니라, 서버 호스트를 설정했기 때문에 나타난 것입니다.

자체 호스팅 모의를 통해 요청 전송

이제 사용해 보세요. 내부 주문 관리 API를 위한 프로젝트에 GET /orders/{orderId} 엔드포인트가 있다고 가정해 보겠습니다. 해당 엔드포인트를 열고 상단의 환경 드롭다운에서 클라우드 환경 대신 Runner Mock을 선택합니다. 요청을 보냅니다.

응답은 러너에서 돌아옵니다. Apidog가 스키마에서 모의 데이터를 생성하기 때문에, 잘 정의된 Order 스키마는 빈 플레이스홀더 대신 실제 값을 반환합니다:

curl http://runner.internal.example.com:80/orders/10583

{
  "orderId": 10583,
  "customerEmail": "amelia.turner@example.com",
  "status": "shipped",
  "total": 148.5,
  "currency": "USD",
  "createdAt": "2026-07-14T09:32:11Z"
}

이 JSON은 공용 인터넷에 전혀 연결되지 않았습니다. 러너가 엔드포인트의 스키마에서 이를 구축하고 네트워크 내부에서 제공했습니다. 위 customerEmail 값과 같은 필드 인식 생성은 Apidog가 스키마의 유형과 필드 이름을 읽는 방식에서 비롯됩니다. 이는 스마트 모의로 실제 모의 데이터 자동 생성에 대한 관련 글에서 다루는 것과 동일한 엔진입니다. 특정 요청이 정확히 무엇을 반환할지 제어하고 싶다면, 엔드포인트에 모의 기대를 추가하고 러너는 클라우드 모의와 동일한 방식으로 그 기대를 제공합니다. 서버가 Apidog의 것이든 사용자의 것이든 좋은 모의 응답을 구축하는 메커니즘은 동일하며, 호스트만 다릅니다. API 모의 뒤에 있는 일반적인 개념은 변하지 않고 적용됩니다.

HTTPS, 데이터 마운트 및 기타 실제 세부 정보

http://127.0.0.1에서 테스트를 실행하는 것은 쉽습니다. 공유 인트라넷 배포에는 팀에 배포하기 전에 알아야 할 몇 가지 까다로운 부분이 있습니다.

HTTPS에는 리버스 프록시가 필요합니다

러너에는 내장된 HTTPS 인증서 지원 기능이 없으며 자동 인증서 프로비저닝도 수행하지 않습니다. 러너는 TLS 인증서를 가져오거나 관리하지 않습니다. https://가 필요하다면, 러너 앞에 리버스 프록시(예: Nginx)를 두어 TLS를 종료하고, 서버 호스트를 프록시의 HTTPS URL로 지정하세요. 프록시가 없다면 http://host:port를 고수하세요. 서버 호스트를 https://로 설정하고 러너가 TLS에 직접 응답할 것이라고 기대하지 마세요. 러너는 그럴 수 없습니다.

포트 4524에서 러너를 전면에 배치하는 최소한의 Nginx 블록은 다음과 같습니다:

server {
    listen 443 ssl;
    server_name runner.example.com;

    ssl_certificate     /etc/ssl/certs/runner.example.com.pem;
    ssl_certificate_key /etc/ssl/private/runner.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4524;
        proxy_set_header Host $host;
    }
}

그러면 서버 호스트는 https://runner.example.com:443이 됩니다. TLS 종료가 팀에 익숙하지 않다면 MDN의 HTTPS 가이드가 좋은 참고 자료가 될 것입니다.

파일 마운트는 경로별로 다릅니다

모의 또는 테스트에 추가 파일이 필요한 경우, 러너는 컨테이너 내부의 고정 경로에서 해당 파일을 예상하므로, 그곳에 마운트해야 합니다:

외부 프로그램은 /app/external-programs/에 들어갑니다.
데이터베이스 연결 구성은 /app/database/database-connections.json에 들어갑니다.
SSL 클라이언트 인증서는 /app/ssl/ssl-client-cert-list.json에 들어갑니다.

재시작 후에도 유지되도록 -v 마운트를 통해 연결하십시오.

재배포 및 업그레이드 동작

새 러너 버전이 출시되면 업그레이드(Upgrade) 옵션이 표시되고, 추가 작업(More Actions) 아래에 재배포(Redeploy)할 수 있는 옵션이 있습니다. 둘 다 실행 중인 컨테이너를 중지하고 새 컨테이너를 시작합니다. 안심할 수 있는 부분은 Apidog 클라이언트의 기존 예약 작업이 재배포 또는 업그레이드에 영향을 받지 않는다는 것입니다. 따라서 컨테이너가 다시 시작되는 순간에만 라이브 서비스가 중단될 뿐, 구성이 손실되지 않습니다.

Apidog CLI로 워크플로우 자동화

여기서 혼란을 막아줄 차이점이 있습니다: 러너는 모의를 제공하고 예약된 작업을 실행할 수 있는 장기 실행 에이전트인 반면, Apidog CLI는 CI를 위한 일회성 테스트 러너입니다. 이들은 다른 도구입니다. CLI는 모의 서버를 제공, 시작 또는 호스팅할 수 없습니다. apidog run mock나 apidog mock serve는 없습니다. CLI의 apidog run은 테스트 시나리오, 테스트 시나리오 폴더 및 테스트 스위트를 실행하고, mock 명령 그룹은 데이터로서 모의 기대치에 대한 CRUD만 수행합니다. 모의 서비스는 러너의 작업이며, CLI의 작업이 아닙니다.

따라서 둘은 이렇게 함께 작동합니다. CLI와 Cursor, Claude Code, Codex와 같은 AI 코딩 에이전트는 프로젝트의 엔드포인트와 스키마를 생성 및 업데이트할 수 있으며, 이를 통해 스펙이 발전함에 따라 모의 출력이 정확하게 유지됩니다. 자체 호스팅 모의가 프론트엔드 작업을 해제한 후, 동일한 프로젝트의 테스트 시나리오는 단일 명령으로 CI에서 헤드리스로 실행되어, 모의가 설명한 계약에 대해 실제 백엔드를 검증합니다:

apidog run -t <scenario_id> -e <env_id> -r html,cli

이 하나의 명령은 라이브 백엔드에 대해 시나리오를 실행하고 HTML 및 CLI 보고서를 작성합니다. 설치는 Node.js v16 이상에서 npm install -g apidog-cli입니다. Apidog CLI 설치 가이드는 apidog login 및 토큰 설정을 다룹니다. 모든 푸시에서 테스트 실행을 수행하려면 Apidog CLI CI/CD 가이드를 사용하여 파이프라인에 연결하십시오. CLI에서 API 모의에 대한 글은 터미널이 모의 정의를 관리하지만 호스팅하지 않는 정확한 이유를 설명합니다.

자주 묻는 질문

팀이 인터넷에 연결할 수 있는 경우에도 자체 호스팅 러너가 필요한가요?

아마도 아닐 것입니다. 클라우드 모의는 배포할 것이 없으며 더 간단한 경로입니다. 아웃바운드 트래픽이 차단되거나 감사되는 경우, 규정 준수 규칙으로 데이터가 내부 인프라에 유지되어야 하는 경우, 또는 환경이 에어갭(air-gapped)된 경우에 러너를 선택하십시오. 호스팅 방식과 관리 방식을 먼저 비교하고 있다면, Apidog 클라우드 모의 가이드가 이 가이드의 자연스러운 동반자입니다.

Apidog CLI가 자체 호스팅 모의 서버를 시작할 수 있습니까?

아니요. CLI는 apidog run으로 테스트를 실행하고, mock 명령 그룹으로 모의 기대치를 데이터로 관리합니다. 모의 트래픽 제공은 General Runner 또는 클라우드 모의가 수행하며, CLI는 절대 하지 않습니다. 하나의 터미널 명령으로 실행 중인 모의를 특정 포트에서 얻기를 바랐다면, 그것은 위에서 설명한 대로 GUI를 통해 설정되는 러너의 작업입니다.

러너가 자체적으로 HTTPS를 지원하나요?

인증서를 제공하거나 자동으로 프로비저닝하지 않습니다. Nginx와 같은 리버스 프록시를 앞에 두어 TLS를 종료한 다음, 서버 호스트를 프록시의 https:// URL로 지정하십시오. 프록시가 없다면 http://호스트:포트를 사용하십시오.

명령을 실행한 후 러너가 나타나지 않는 이유는 무엇입니까?

팀 리소스(Team Resources)를 열고 General Runner로 이동하여 새로고침 버튼을 클릭하십시오. 등록에는 잠시 지연이 있을 수 있습니다. 여전히 나타나지 않으면 docker ps로 컨테이너가 실행 중인지, 그리고 호스트가 Apidog에서 연결 가능한지 확인하십시오. 오프라인(Offline) 상태는 연결이 끊어졌음을 의미하며, 시작됨(Started) 상태가 원하는 상태입니다.

여러 팀이 하나의 러너를 공유하여 전역 모의 서비스를 제공할 수 있나요?

러너는 배포한 팀에 등록되며, 해당 팀의 Runner Mock 환경은 프로젝트별로 나타납니다. 모의 환경을 공유하는 분산 팀을 운영하는 경우, 전역 팀 간에 모의 환경 공유 가이드의 패턴이 몇 개의 러너를 어디에 설정해야 할지 결정하는 데 도움이 될 것입니다.

마무리

General Runner를 이용한 자체 호스팅 모의는 모의 디자인이 항상 Apidog 프로젝트에 있던 곳에 그대로 유지되면서 요청 데이터를 제어하는 인프라에 보관합니다. Docker 컨테이너 하나를 배포하고 서버 호스트를 설정하면 Runner Mock 환경이 나머지를 처리합니다. 클라우드 사용이 제한될 때 사용하고, 그렇지 않을 때는 클라우드 모의를 고수하세요. 자체 네트워크에서 모의를 실행할 준비가 되셨나요? Apidog를 다운로드하고, 러너를 배포하고, 인트라넷을 벗어나지 않고 첫 Runner Mock 응답을 제공해 보세요.