DEV Community

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

Posted on • Originally published at apidog.com

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

일부 팀은 트래픽을 클라우드로 보낼 수 없습니다. 기업 방화벽이 서드파티 서비스로의 아웃바운드 호출을 차단할 수 있고, 규정 준수 규칙상 요청 및 응답 데이터가 사용자가 제어하는 머신에만 남아야 할 수도 있습니다. 에어갭(air-gapped) 환경이라면 인트라넷 외부로 어떤 요청도 보낼 수 없습니다. 이런 경우에는 모의 데이터가 가짜이더라도 외부 인프라에 호스팅된 모의 URL을 사용할 수 없습니다.

지금 Apidog 사용해 보기

Apidog의 자체 호스팅 러너(Self-hosted Runner)는 이 문제를 해결합니다. Apidog 클라우드 모의 서버 대신, 사용자가 관리하는 서버에 작은 프로그램을 배포해 네트워크 내부에서 모의 응답을 반환하게 합니다. 모의 설계와 API 정의는 Apidog 프로젝트에 유지되고, 실제 응답을 제공하는 서비스만 내부 인프라로 이동합니다.

이 글에서는 다음을 다룹니다.

  • 자체 호스팅 러너가 필요한 상황
  • Docker로 General Runner를 배포하는 방법
  • Runner Mock 환경을 활성화하는 방법
  • HTTPS와 데이터 마운트 구성
  • General Runner와 Apidog CLI의 역할 차이

더 넓은 사용 사례는 자체 호스팅 API 모의 서버 가이드에서 확인할 수 있습니다. API 스키마 기반 모의의 기반이 되는 표준은 OpenAPI Initiative에서 확인하세요.

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

Apidog 자체 호스팅 러너는 사용자가 관리하는 서버에서 실행하는 자동화 프로그램입니다. 공식 명칭은 General Runner이며, 다음 작업을 수행합니다.

  1. 예약된 자동 테스트 실행
  2. API 문서 가져오기
  3. 모의 응답 반환

이 글에서는 세 번째 기능인 자체 호스팅 모의 응답에 집중합니다.

General Runner 구성 화면

General Runner를 배포하고 서버 호스트를 설정하면 프로젝트에 Runner Mock 환경이 자동으로 추가됩니다. 이 환경을 선택해 요청을 보내면 Apidog 클라우드 모의가 아닌 자체 호스팅 러너가 응답합니다.

즉, 다음은 그대로 유지됩니다.

  • API 설계
  • 스키마
  • 모의 기대값(Mock Expectation)
  • 생성 데이터 규칙

바뀌는 것은 응답을 제공하는 머신뿐입니다. 요청 트래픽은 네트워크 외부로 나가지 않습니다.

러너를 선택해야 하는 경우

인터넷 연결과 외부 SaaS 사용에 제약이 없다면 Apidog 클라우드 모의가 더 간단합니다. 별도 서버나 Docker 컨테이너를 운영할 필요가 없기 때문입니다.

다음 조건 중 하나에 해당하면 자체 호스팅 러너를 고려하세요.

  • 외부 호스트로의 아웃바운드 트래픽이 차단되거나 엄격히 감사된다.
  • 규정 준수 정책상 요청 데이터가 내부 인프라에 남아야 한다.
  • 환경이 에어갭 상태라 클라우드 엔드포인트에 연결할 수 없다.
  • 공용 인터넷이 아닌 내부 LAN에서 모의 응답 지연 시간을 측정해야 한다.

반대로 이런 요구 사항이 없다면 Docker 호스트를 추가로 관리하는 것은 불필요한 운영 오버헤드가 될 수 있습니다.

설정에는 팀 또는 프로젝트 관리자 권한이 필요합니다. General Runner는 팀 리소스에서 관리되며, 관리자만 관련 설정을 열 수 있습니다.

시작하기 전에 필요한 것

General Runner는 Docker 컨테이너로 제공됩니다. 시작 전에 다음을 준비하세요.

  • Docker 20.10.0 이상
  • 권장 Docker 버전: 20.10.13 이상
  • Apidog 클라이언트 및 Apidog 서비스와 연결 가능한 Linux, macOS 또는 Windows 호스트
  • Apidog 팀 관리자 권한
  • 내부 네트워크에서 접근 가능한 안정적인 IP 또는 호스트 이름

Docker 버전을 확인합니다.

docker --version
Enter fullscreen mode Exit fullscreen mode

인트라넷 환경에서는 일반적으로 내부 DNS 이름 또는 고정 IP를 사용합니다. 예를 들면 다음과 같습니다.

runner.internal.example.com
Enter fullscreen mode Exit fullscreen mode

General Runner 배포

Apidog는 토큰이 포함된 Docker 실행 명령을 자동 생성합니다. 토큰을 직접 작성할 필요는 없습니다.

1. 배포 명령 생성

Apidog에서 다음 경로로 이동합니다.

  1. Apidog 홈에서 팀을 선택합니다.
  2. 오른쪽 사이드바에서 리소스(Resources) 를 클릭합니다.
  3. General Runner 배포(Deploy General Runner) 를 선택합니다.
  4. 팝업에서 실행 환경을 구성합니다.

구성 항목은 다음과 같습니다.

  • 서버 OS: Linux, macOS 또는 Windows
  • Docker 이미지
    • General: Node.js 18, Java 21, Python 3, PHP 8 포함
    • Slim: Node.js 18만 포함
    • Custom: 추가 런타임이 필요한 경우 자체 Dockerfile 사용
  • 노출 포트(Exposed Port): -p 옵션으로 호스트 포트와 러너 내부 포트를 연결
  • 마운트된 데이터 디렉터리(Mounted Data Directory): -v 옵션으로 컨테이너 데이터를 호스트에 유지

예를 들어 -p 80:4524는 호스트의 80 포트를 러너 컨테이너의 4524 포트에 연결합니다.

생성된 명령에는 토큰이 포함되며 한 번만 표시됩니다. 명령을 잃어버리면 기존 토큰을 복구하는 대신 새 명령을 생성해야 합니다. 생성 직후 안전한 위치에 저장하세요.

2. 서버에서 컨테이너 실행

Apidog가 생성한 명령을 서버 터미널에서 실행합니다. 실제 명령에는 생성된 토큰이 포함됩니다.

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

컨테이너가 정상 실행 중인지 확인합니다.

docker ps
Enter fullscreen mode Exit fullscreen mode

출력에 apidog-runner 컨테이너와 포트 매핑이 표시되어야 합니다.

예시:

CONTAINER ID   IMAGE                  PORTS
a1b2c3d4e5f6   apidog/runner:latest   0.0.0.0:80->4524/tcp
Enter fullscreen mode Exit fullscreen mode

3. Apidog에서 등록 상태 확인

다시 Apidog로 돌아가 다음 경로를 엽니다.

팀 리소스(Team Resources) → General Runner
Enter fullscreen mode Exit fullscreen mode

새로고침 버튼을 클릭합니다. 새 러너가 시작됨(Started) 상태로 표시되면 등록이 완료된 것입니다.

상태별 의미는 다음과 같습니다.

상태 의미 조치
시작됨(Started) Apidog와 연결되어 작업을 처리할 수 있음 정상 상태
중지됨(Stopped) Apidog에서 수동으로 중지됨 필요하면 다시 시작
오프라인(Offline) Apidog와 연결이 끊김 컨테이너 및 네트워크 경로 확인

처음에는 등록이 보이지 않을 수 있습니다. 잠시 기다린 뒤 새로고침하세요.

Runner Mock 환경 활성화

러너를 배포한 뒤에는 모의 트래픽이 러너를 향하도록 서버 호스트를 설정해야 합니다.

  1. 팀 리소스(Team Resources) 에서 General Runner를 엽니다.
  2. 서버 호스트(Server Host) 필드를 찾습니다.
  3. 러너에 접근할 수 있는 URL을 입력합니다.

일반적인 예시는 다음과 같습니다.

# 로컬 테스트
http://127.0.0.1:80

# 내부 네트워크 공유 호스트
http://runner.internal.example.com:80

# TLS 종료 프록시 뒤
https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

서버 호스트를 저장하면 Apidog가 프로젝트에 Runner Mock 환경을 자동 연결합니다.

프로젝트에서 다음 경로로 이동해 확인하세요.

환경 관리(Environment Management)
Enter fullscreen mode Exit fullscreen mode

환경 목록에 Runner Mock이 표시되면 설정이 완료된 것입니다. 이 환경은 수동으로 생성하는 환경이 아니라, 서버 호스트 설정에 따라 자동으로 추가됩니다.

자체 호스팅 모의로 요청 보내기

예를 들어 주문 API에 다음 엔드포인트가 있다고 가정해 보겠습니다.

GET /orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

테스트 절차는 간단합니다.

  1. Apidog에서 GET /orders/{orderId} 엔드포인트를 엽니다.
  2. 상단 환경 드롭다운에서 클라우드 환경 대신 Runner Mock을 선택합니다.
  3. 요청을 전송합니다.

내부 호스트에 직접 요청하면 다음과 같은 형태가 됩니다.

curl http://runner.internal.example.com:80/orders/10583
Enter fullscreen mode Exit fullscreen mode

스키마가 잘 정의되어 있다면 러너는 스키마 기반 모의 데이터를 반환합니다.

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

이 요청과 응답은 공용 인터넷을 거치지 않습니다. 러너가 API 스키마를 바탕으로 모의 데이터를 생성하고 내부 네트워크에서 제공합니다.

customerEmail처럼 필드 이름과 타입을 반영하는 생성 방식은 Apidog의 스마트 모의 기능과 연결됩니다. 자세한 내용은 스마트 모의로 실제 모의 데이터 자동 생성을 참고하세요.

특정 요청에 대해 항상 같은 응답을 반환해야 한다면 엔드포인트에 모의 기대값을 추가하면 됩니다. 러너는 클라우드 모의와 동일한 방식으로 해당 기대값을 제공합니다. 모의 응답을 설계하는 방식은 같고, 응답을 호스팅하는 위치만 다릅니다.

기본 개념은 API 모의 가이드에서도 확인할 수 있습니다.

HTTPS, 데이터 마운트 및 운영 세부 사항

로컬에서 http://127.0.0.1로 테스트하는 것은 간단합니다. 하지만 팀이 공유하는 인트라넷 환경에서는 HTTPS, 볼륨, 업그레이드 동작을 미리 확인해야 합니다.

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

General Runner는 TLS 인증서를 직접 제공하거나 자동으로 프로비저닝하지 않습니다. HTTPS가 필요하면 러너 앞에 Nginx 같은 리버스 프록시를 배치해 TLS를 종료해야 합니다.

구성 흐름은 다음과 같습니다.

클라이언트
  ↓ HTTPS
Nginx 리버스 프록시
  ↓ HTTP
General Runner (4524 포트)
Enter fullscreen mode Exit fullscreen mode

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;
    }
}
Enter fullscreen mode Exit fullscreen mode

이 경우 Apidog의 서버 호스트에는 다음을 입력합니다.

https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

TLS 종료 방식이 익숙하지 않다면 Nginx HTTPS 설정 문서와 MDN의 HTTPS 가이드를 참고하세요.

파일 마운트 경로

모의 또는 테스트 작업에서 외부 파일이 필요하다면, 러너가 기대하는 컨테이너 내부 경로에 파일을 마운트해야 합니다.

용도 컨테이너 내부 경로
외부 프로그램 /app/external-programs/
데이터베이스 연결 구성 /app/database/database-connections.json
SSL 클라이언트 인증서 목록 /app/ssl/ssl-client-cert-list.json

예를 들어 호스트의 외부 프로그램 디렉터리를 컨테이너에 연결하려면 다음처럼 -v 옵션을 사용합니다.

docker run -d \
  --name apidog-runner \
  -p 80:4524 \
  -v /opt/apidog-runner/data:/app/data \
  -v /opt/apidog-runner/external-programs:/app/external-programs \
  apidog/runner:latest \
  --token <YOUR_GENERATED_TOKEN>
Enter fullscreen mode Exit fullscreen mode

데이터를 컨테이너 내부에만 저장하면 재생성 또는 재배포 시 유지되지 않을 수 있습니다. 필요한 파일은 항상 호스트 볼륨으로 마운트하세요.

재배포와 업그레이드

새 러너 버전이 제공되면 Upgrade 옵션이 표시될 수 있습니다. More Actions 메뉴에서는 Redeploy도 실행할 수 있습니다.

두 작업 모두 일반적으로 다음 순서로 진행됩니다.

  1. 기존 컨테이너 중지
  2. 새 컨테이너 시작
  3. 러너 재등록 및 작업 재개

기존 예약 작업 구성은 재배포나 업그레이드로 사라지지 않습니다. 다만 컨테이너가 재시작되는 동안에는 일시적으로 모의 응답이 중단될 수 있으므로, 운영 환경에서는 배포 시간을 고려하세요.

Apidog CLI로 워크플로우 자동화

여기서 자주 혼동하는 부분이 있습니다.

  • General Runner: 장기 실행 에이전트. 모의 응답을 제공하고 예약 작업을 실행합니다.
  • Apidog CLI: CI 환경에서 테스트를 실행하는 일회성 도구입니다.

Apidog CLI는 모의 서버를 시작하거나 호스팅하지 않습니다. 다음과 같은 명령은 없습니다.

apidog run mock
apidog mock serve
Enter fullscreen mode Exit fullscreen mode

CLI의 역할은 다음과 같습니다.

  • apidog run: 테스트 시나리오, 시나리오 폴더, 테스트 스위트 실행
  • mock 명령 그룹: 모의 기대값을 데이터로 생성, 조회, 수정, 삭제

즉, 모의 트래픽을 제공하는 역할은 General Runner 또는 Apidog 클라우드 모의가 담당합니다. CLI는 이를 대신하지 않습니다.

CI에서 실제 백엔드 검증하기

자체 호스팅 모의로 프론트엔드 개발을 진행하는 동안, 같은 프로젝트의 테스트 시나리오를 CI에서 실행해 실제 백엔드를 검증할 수 있습니다.

apidog run -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

이 명령은 지정한 환경에서 시나리오를 실행하고 HTML 및 CLI 보고서를 생성합니다.

Apidog CLI 설치에는 Node.js v16 이상이 필요합니다.

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

로그인과 토큰 설정은 Apidog CLI 설치 가이드를 참고하세요. 모든 푸시마다 테스트를 실행하려면 Apidog CLI CI/CD 가이드를 사용해 파이프라인에 연결할 수 있습니다.

터미널에서 모의 기대값을 관리하는 방식은 CLI에서 API 모의에서 확인할 수 있습니다. 핵심은 CLI가 모의 정의를 관리할 수는 있지만, 모의 서비스를 호스팅하지는 않는다는 점입니다.

자주 묻는 질문

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

대부분의 경우 필요하지 않습니다. 클라우드 모의는 별도 서버를 배포하거나 운영하지 않아도 되므로 더 간단합니다.

다음 상황에서는 러너를 선택하세요.

  • 외부 트래픽이 차단되거나 감사 대상인 경우
  • 데이터가 내부 인프라에 남아야 하는 경우
  • 에어갭 환경인 경우
  • 내부 네트워크 기준의 모의 지연 시간을 검증해야 하는 경우

클라우드 방식과 비교하려면 Apidog 클라우드 모의 가이드를 참고하세요.

Apidog CLI로 자체 호스팅 모의 서버를 시작할 수 있나요?

아니요. CLI는 apidog run으로 테스트를 실행하고, mock 명령 그룹으로 모의 기대값을 관리합니다.

모의 HTTP 트래픽을 실제로 제공하는 역할은 General Runner 또는 클라우드 모의가 담당합니다.

러너가 HTTPS를 직접 지원하나요?

인증서를 직접 제공하거나 자동으로 프로비저닝하지 않습니다. Nginx 같은 리버스 프록시에서 TLS를 종료한 뒤, Apidog 서버 호스트에 프록시의 https:// URL을 설정하세요.

리버스 프록시가 없다면 다음처럼 HTTP를 사용합니다.

http://호스트:포트
Enter fullscreen mode Exit fullscreen mode

명령을 실행했는데 러너가 Apidog에 나타나지 않습니다. 무엇을 확인해야 하나요?

다음 순서로 확인하세요.

  1. 팀 리소스 → General Runner에서 새로고침합니다.
  2. 등록 지연이 있을 수 있으므로 잠시 기다린 뒤 다시 새로고침합니다.
  3. 서버에서 컨테이너 상태를 확인합니다. 
docker ps
Enter fullscreen mode Exit fullscreen mode
  1. 컨테이너 로그를 확인합니다. 
docker logs apidog-runner
Enter fullscreen mode Exit fullscreen mode
  1. 러너 호스트가 Apidog와 통신 가능한 네트워크 경로에 있는지 확인합니다.

Offline 상태는 연결이 끊긴 상태를 의미합니다. 정상 상태는 Started입니다.

여러 팀이 하나의 러너를 공유할 수 있나요?

러너는 배포한 팀에 등록되며, 해당 팀의 프로젝트에 Runner Mock 환경이 연결됩니다. 여러 지역 또는 여러 팀에서 모의 환경을 공유해야 한다면 전역 팀 간에 모의 환경 공유 가이드를 참고해 러너 배치 전략을 결정하세요.

마무리

General Runner를 사용하면 API 모의 설계는 Apidog 프로젝트에 유지하면서 요청 데이터와 응답 트래픽은 사용자가 제어하는 인프라에 남길 수 있습니다.

구현 흐름은 다음과 같습니다.

  1. Docker가 설치된 내부 호스트를 준비합니다.
  2. Apidog에서 General Runner 배포 명령을 생성합니다.
  3. 서버에서 Docker 컨테이너를 실행합니다.
  4. Apidog에서 러너가 Started 상태인지 확인합니다.
  5. 서버 호스트를 설정합니다.
  6. 프로젝트에서 Runner Mock 환경을 선택해 요청을 보냅니다.

클라우드 사용이 제한되는 환경이라면 자체 호스팅 러너가 적합합니다. 그렇지 않다면 운영 부담이 적은 클라우드 모의를 사용하는 편이 더 단순합니다.

시작하려면 Apidog를 다운로드하고, 내부 서버에 러너를 배포한 뒤 첫 번째 Runner Mock 응답을 확인해 보세요.

Top comments (0)