ServBay와 Docker 협업 FAQ

로컬 웹 개발 시 ServBay를 사용하면서 Docker로 컨테이너 환경을 병행하려는 경우가 많습니다. 본 FAQ는 macOS 및 Windows 환경에서 ServBay와 Docker를 함께 사용할 때 생길 수 있는 주요 이슈와 해결법, Docker에서 ServBay 서비스 접근 및 Docker 컨테이너 내 애플리케이션을 ServBay로 역방향 프록시하는 방법을 설명합니다.

Q1: ServBay가 내 시스템의 `hosts` 파일을 수정하는 이유는? 수정하지 않게 할 수 있나요?

ServBay는 시스템의 hosts 파일에 예를 들어 mysite.servbay.demo 127.0.0.1 같은 항목을 추가하여, mysite.servbay.demo와 같은 맞춤 도메인으로 로컬 개발 웹사이트에 접속할 수 있도록 해줍니다. 실제로 이 웹사이트들은 로컬 PC의 127.0.0.1에서 구동됩니다.

그러나 Docker의 특성상, host 시스템(macOS 또는 Windows)의 hosts 파일을 읽어들여 mysite.servbay.demo가 127.0.0.1로 해석되는데, 이때 Docker 컨테이너의 루프백 주소로 연결되어 Docker 내부 서비스에 접근하게 되는 문제가 생깁니다.

핵심 원리:

ServBay에서 새 사이트를 만들 때 입력한 도메인(예: example.servbay.demo)은 자동으로 127.0.0.1에 바인딩됩니다.
이는 개발에 용이한 로컬 도메인 접속을 위한 표준 방식입니다. 만약 hosts 파일을 수정하지 않는다면, http://127.0.0.1:PORT처럼만 접근 가능하고, 커스텀 도메인 사용은 불가합니다.

수정하지 않게 할 수 있나요?

이론상 ServBay가 추가한 hosts 항목을 수동으로 삭제할 수 있지만, 그럴 경우 ServBay에서 설정한 도메인으로 로컬 사이트에 접속할 수 없으므로, ServBay가 제공하는 편리한 개발 경험이 사라집니다. ServBay의 핵심 기능은 쉽고 빠르게 로컬 웹사이트를 생성하고 도메인으로 접근하는 것입니다. 특정 도메인에 대해 ServBay가 hosts 파일을 수정하지 않기를 원한다면, 해당 도메인으로 웹사이트를 ServBay에 생성하지 않는 게 좋습니다.

대다수의 로컬 개발 상황에서는 ServBay가 hosts 파일을 자동 관리하는 것이 바람직하며, 개발 흐름을 크게 단순화합니다.

Q2: Docker 컨테이너가 ServBay로 관리되는 웹사이트(예: `mysite.servbay.demo`)에 도메인으로 올바르게 접속하려면?

매우 흔한 요구지만, 제대로 처리하지 않으면 문제를 겪을 수 있습니다. ServBay가 호스트(macOS 또는 Windows)에서 구동중인 웹사이트(예: mysite.servbay.demo, hosts에서 127.0.0.1로 해석)를 Docker 컨테이너에서 접속할 경우, 컨테이너 내부의 127.0.0.1은 호스트가 아니라 컨테이너 자신의 주소입니다.

잘못된 방법: URL의 호스트명에 host.docker.internal을 직접 사용

Docker Desktop for Mac/Windows는 컨테이너 내부에서 호스트의 IP로 연결될 수 있는 특수 DNS 이름 host.docker.internal을 제공합니다. 하지만 이것을 직접 URL의 호스트명으로 사용하여 ServBay 사이트에 접근하는 것은 추천하지 않습니다 (예: http://host.docker.internal/로 접속 시 mysite.servbay.demo로 기대하는 결과가 나오지 않음).

이 방식으로 접근할 경우, ServBay 웹 서버(Caddy/Nginx 등)에 전달되는 HTTP 요청의 Host 헤더가 host.docker.internal이 되는데, ServBay 웹 서버는 이 헤더를 기준으로 사이트를 식별합니다. Host가 mysite.servbay.demo가 아니라면 제대로 라우팅이 되지 않고, HTTPS라면 SNI(Server Name Indication) 오류가 생깁니다. 왜냐하면 SSL 인증서는 mysite.servbay.demo에 발급되어 있고 host.docker.internal에는 없기 때문입니다.

올바른 해결책: Docker 컨테이너 기동시 extra_hosts 사용

Docker 컨테이너의 /etc/hosts에 ServBay 사이트의 도메인을 호스트 IP로 매핑하여, 컨테이너에서도 원래 도메명으로 요청하도록 해야 합니다. 이를 위해 extra_hosts(docker-compose.yml)나 --add-host(docker run) 옵션으로 도메인을 host.docker.internal 또는 더 권장되는 host-gateway에 매핑합니다.

docker run 사용 예:
bash
```
docker run --add-host=mysite.servbay.demo:host-gateway ... your_image
```
1
(host-gateway는 Docker가 자동으로 호스트 내부 IP로 변환합니다. Docker 20.10+ 기준으로 이는 사실상 host.docker.internal과 비슷하지만 더 근본적인 매핑입니다.)

docker-compose.yml 사용 예:

yaml

version: '3.8' # 혹은 그 이상
services:
  myapp:
    image: your_image
    extra_hosts:
      - "mysite.servbay.demo:host-gateway" # 또는 "mysite.servbay.demo:host.docker.internal"
    # ... 기타 설정

이렇게 설정하면, Docker 컨테이너 내부에서

http://mysite.servbay.demo 혹은 https://mysite.servbay.demo로 접근할 때,
/etc/hosts에서 해당 도메인을 호스트 IP로 해석합니다.
ServBay 웹 서버(호스트)로 요청이 들어가고,
HTTP Host 헤더가 정상적으로 mysite.servbay.demo여서 정확히 해당 사이트로 라우팅되고, SSL 인증서도 올바르게 제공됩니다(HTTPS 사용시).

Q3: Docker 컨테이너가 ServBay 관리 데이터베이스(MySQL, PostgreSQL 등) 또는 기타 비HTTP 서비스에 접속하려면?

도메인 기반 웹 서비스 접근과 달리, 데이터베이스나 SNI가 필요 없는 TCP 서비스의 경우 host.docker.internal을 서버 호스트명으로 사용하는 것이 추천되고 정상적으로 동작합니다.

방법:

ServBay의 데이터베이스 패키지(혹은 서비스)가 실행중임을 확인하고, 외부(호스트) 연결을 허용하도록 설정되어 있어야 합니다(기본 설정이면 로컬 개발은 보통 가능).
Docker 컨테이너 내부에서 데이터베이스 접속시:
- 호스트명(Hostname/Server): host.docker.internal
- 포트(Port): ServBay에서 해당 데이터베이스가 사용하는 포트(예, MySQL 기본 3306, PostgreSQL 기본 5432)
- 유저/비밀번호: ServBay에서 생성한 계정 정보
예시 (ServBay 관리 MySQL 접속): ServBay에서 MySQL이 3306에 실행중이라면, Docker 컨테이너 앱에서는
- 호스트: host.docker.internal
- 포트: 3306
- 계정: your_db_user
- 비번: your_db_password 등의 설정으로 연결합니다.

Q4: Docker 컨테이너가 (extra_hosts로 도메인 매핑된) ServBay HTTPS 사이트(ServBay User CA 인증서 사용)에 접근시, CA 신뢰는 어떻게 설정하나요?

Q2에서 설명한대로, extra_hosts 또는 --add-host로 예를 들어 secure.servbay.demo를 host-gateway로 연결했다고 가정합니다. 이 사이트가 ServBay User CA로 발급받은 SSL 인증서를 쓴다면, Docker 컨테이너는 기본적으로 해당 CA를 신뢰하지 않아 SSL 연결에 실패할 수 있습니다.

ServBay CA 파일 위치:

ServBay User CA 루트 인증서:
- macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt
ServBay User CA, Public CA, Mozilla 루트 인증서가 포함된 PEM 파일:
- macOS(ARM): /Applications/ServBay/package/common/openssl/3.2/cacert.pem
- macOS(Intel): /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem
- Windows: C:\ServBay\package\common\openssl\3.3\cacert.pem

해결방법 요약:

Docker 컨테이너에서 ServBay User CA를 신뢰시키는 방법은 다양하며, 대표적으로 아래와 같습니다:

방법1: Docker 이미지 빌드시 시스템 레벨 신뢰(Dockerfile)
방법2: 앱별 신뢰(볼륨 마운트 및 환경변수)
방법3: 런타임에 시스템 신뢰(볼륨 마운트, 커맨드 스크립트)

방법1: Docker 이미지 빌드시 신뢰(Dockerfile)

이미지 빌드시 CA 인증서를 OS 신뢰 저장소에 등록하는 방법입니다.

CA 파일 준비: ServBay User CA 루트 인증서를 Dockerfile과 같은 디렉터리에 복사합니다.
- macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt

Dockerfile 예시 (Debian/Ubuntu):

dockerfile

# Dockerfile
FROM ubuntu:latest
COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && \
    update-ca-certificates && \
    rm -rf /var/lib/apt/lists/*

Dockerfile 예시 (Alpine):

dockerfile

# Dockerfile
FROM alpine:latest
COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
RUN apk add --no-cache ca-certificates && update-ca-certificates

docker-compose 빌드 예시:

yaml

# docker-compose.yml
version: '3.8'
services:
  myapp:
    build:
      context: ./app_service # Dockerfile 및 ServBay-Private-CA-ECC-Root.crt 포함
      dockerfile: Dockerfile
    extra_hosts: ["secure.servbay.demo:host-gateway"]

방법2: 앱별 신뢰(볼륨 마운트 및 환경변수)

CA 인증서를 컨테이너에 마운트하고, 앱에서 환경변수로 참조하게 하는 방법입니다.

docker-compose.yml 예시:

yaml

version: '3.8'
services:
  myapp:
    image: some-base-image
    volumes:
      # macOS 경로 예
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
      # Windows 경로 예 (실 OS에 맞게 조정)
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
    environment:
      # Node.js 예시:
      - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
      # Python(requests) 예시:
      # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
      # 골든 환경변수 예:
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

사용할 앱 별로 환경변수 세팅법은 공식문서를 참고하세요.

방법3: 런타임에 시스템 신뢰 업데이트(볼륨 마운트+시작 커맨드)

볼륨 마운트와 컨테이너 시작 커맨드를 활용해 컨테이너 OS 신뢰 저장소를 업데이트합니다. 이미지 수정없이 전체 시스템 신뢰를 원하는 경우 적합합니다.

docker-compose.yml 예시(Debian/Ubuntu 기반):

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # update-ca-certificates 호환 이미지
    volumes:
      # macOS 경로 예
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      # Windows 경로 예 (실 OS에 맞게 조정)
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    command: >
      sh -c "
        echo 'Attempting to update CA certificates...' &&
        if command -v update-ca-certificates > /dev/null; then
          if [ ! -f /usr/bin/update-ca-certificates ]; then apt-get update && apt-get install -y --no-install-recommends ca-certificates; fi &&
          update-ca-certificates &&
          echo 'CA certificates updated.'
        else
          echo 'update-ca-certificates command not found, skipping CA update.'
        fi &&
        echo 'Starting application...' &&
        exec your_original_application_command_here # 실제 앱 기동 커맨드로 교체
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # root 권한이 필요할 수 있습니다. entrypoint에서 권한 변경 등 추가 처리 가능.

주의사항:

커맨드 수정 복잡도: 원래 앱 실행 커맨드를 잘 추가해야 합니다.
권한: 보통 root가 필요합니다.
패키지 의존성: ca-certificates 및 update-ca-certificates 설치 필요. 예시에서는 자동설치도 포함.
부팅 시간: 컨테이너 기동시마다 실행됨.
Alpine: Alpine의 경우 커맨드는 apk add --no-cache ca-certificates && update-ca-certificates입니다.

어떤 방법을 선택해야 할까?

커스텀 이미지를 빌드 가능하고 전체 시스템 신뢰가 필요하다면 방법1이 가장 좋습니다.
이미지를 건들지 않고 앱별 신뢰만 필요하다면 방법2가 편리합니다.
이미지는 건들지 않고 시스템 신뢰가 필요하다면 방법3을 권장합니다.

공인 CA(예: Let's Encrypt) 인증서를 쓰는 경우: ServBay 웹사이트가 ACME(예: Let's Encrypt) 등 공인 CA에서 발급받은 인증서를 사용한다면, 대부분의 Docker 베이스 이미지는 이미 해당 CA를 신뢰하고 있으므로 별도의 작업이 필요하지 않습니다.

Q5: Docker 컨테이너 내 애플리케이션에 도메인을 부여하고 ServBay로 역방향 프록시하려면?

예를 들어, Node.js 앱을 Docker 컨테이너 내에서 3000번 포트로 구동중이라고 할 때, ServBay에서 myapp.servbay.demo 같은 도메인을 부여하여 호스트 브라우저로 접근하고, SSL 인증서도 관리하고 싶을 경우입니다.

방법:

Docker 컨테이너를 실행하면서 포트를 호스트의 127.0.0.1로 바인딩: 컨테이너의 애플리케이션 포트를 호스트의 로컬 포트로 바인딩하여 외부로부터 직접 노출되지 않게 해야 합니다.
bash
```
# 예시: 컨테이너 내부 3000번 포트 → 호스트 127.0.0.1:3001로 바인딩
docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image
```
1
2
이제 localhost의 http://127.0.0.1:3001에서 접근 가능합니다.
ServBay에서 새 사이트 생성 및 역방향 프록시 설정:
- ServBay 관리 페이지 접속
- “사이트 추가” 클릭
- 도메인: 사용하고 싶은 도메인 입력 (예: myapp.servbay.demo)
- 사이트 유형: “역방향 프록시” 선택
- IP 주소: 127.0.0.1 입력
- 포트: 1번 단계에서 바인딩한 포트 입력 (예: 3001)
- “저장” 또는 “추가” 클릭
(선택) SSL 설정: 사이트 추가 후 ServBay 설정에서 SSL도 활성화할 수 있습니다. ServBay는 ACME로 Let's Encrypt 등 공인 인증서를 자동 발급하거나, ServBay User CA/Public CA도 편하게 적용할 수 있습니다. SSL은 ServBay에서 처리되며, ServBay→Docker 연결은 일반 HTTP(http://127.0.0.1:3001)로 남을 수 있습니다.
접속 테스트: ServBay 설정이 끝나면 브라우저에서 http://myapp.servbay.demo 또는 SSL 설정시 https://myapp.servbay.demo로 정상 연결되는지 확인하세요. ServBay가 요청을 Docker 컨테이너 내 애플리케이션으로 프록시합니다.

동작 흐름: 사용자 브라우저 → https://myapp.servbay.demo → ServBay(SSL 처리, 프록시 규칙 매칭) → http://127.0.0.1:3001 → Docker 컨테이너 내 앱

요약

ServBay는 macOS 및 Windows에서 로컬 웹 개발을 매우 편리하게 만들어줍니다. Docker와 함께 사용할 때:

Docker 컨테이너에서 ServBay 웹사이트에 접근하려면 extra_hosts 또는 --add-host로 도메인을 host-gateway에 매핑하여 Host 헤더/SNI 문제 없이 정상 연결하세요.
Docker 컨테이너에서 ServBay의 데이터베이스/비HTTP 서비스에 접근하려면 host.docker.internal을 서버로 사용하면 쉽고 효과적입니다.
ServBay User CA가 발급한 SSL 인증서를 Docker 컨테이너에서 신뢰하려면 CA 인증서를 Docker 이미지에 복사하고 신뢰 저장소를 업데이트하세요.
Docker 컨테이너 내 앱에 ServBay를 통한 도메인 및 프록시를 적용하려면 ServBay에서 "역방향 프록시" 사이트로 추가하고, 해당 컨테이너 포트(호스트 127.0.0.1 바인딩)에 연결하세요.

항상 ServBay의 관련 패키지(웹 서버, 데이터베이스 등)가 정상 실행되고, Docker 컨테이너 및 네트워크 바인딩이 올바르게 구성되어 있는지 점검하세요.

ServBay와 Docker 협업 FAQ ​

Q1: ServBay가 내 시스템의 hosts 파일을 수정하는 이유는? 수정하지 않게 할 수 있나요? ​

Q2: Docker 컨테이너가 ServBay로 관리되는 웹사이트(예: mysite.servbay.demo)에 도메인으로 올바르게 접속하려면? ​

Q3: Docker 컨테이너가 ServBay 관리 데이터베이스(MySQL, PostgreSQL 등) 또는 기타 비HTTP 서비스에 접속하려면? ​

Q4: Docker 컨테이너가 (extra_hosts로 도메인 매핑된) ServBay HTTPS 사이트(ServBay User CA 인증서 사용)에 접근시, CA 신뢰는 어떻게 설정하나요? ​

방법1: Docker 이미지 빌드시 신뢰(Dockerfile) ​

방법2: 앱별 신뢰(볼륨 마운트 및 환경변수) ​

방법3: 런타임에 시스템 신뢰 업데이트(볼륨 마운트+시작 커맨드) ​

Q5: Docker 컨테이너 내 애플리케이션에 도메인을 부여하고 ServBay로 역방향 프록시하려면? ​

요약 ​

ServBay와 Docker 협업 FAQ

Q1: ServBay가 내 시스템의 `hosts` 파일을 수정하는 이유는? 수정하지 않게 할 수 있나요?

Q2: Docker 컨테이너가 ServBay로 관리되는 웹사이트(예: `mysite.servbay.demo`)에 도메인으로 올바르게 접속하려면?

Q3: Docker 컨테이너가 ServBay 관리 데이터베이스(MySQL, PostgreSQL 등) 또는 기타 비HTTP 서비스에 접속하려면?

Q4: Docker 컨테이너가 (extra_hosts로 도메인 매핑된) ServBay HTTPS 사이트(ServBay User CA 인증서 사용)에 접근시, CA 신뢰는 어떻게 설정하나요?

방법1: Docker 이미지 빌드시 신뢰(Dockerfile)

방법2: 앱별 신뢰(볼륨 마운트 및 환경변수)

방법3: 런타임에 시스템 신뢰 업데이트(볼륨 마운트+시작 커맨드)

Q5: Docker 컨테이너 내 애플리케이션에 도메인을 부여하고 ServBay로 역방향 프록시하려면?

요약