ServBay와 Docker 연동 FAQ (자주 묻는 질문)

ServBay를 활용해 macOS에서 로컬 웹 개발을 진행할 때, Docker를 결합해 컨테이너 환경을 구축하고자 할 수 있습니다. 본 FAQ는 macOS 환경에서 ServBay와 Docker를 함께 사용할 때 직면할 수 있는 일반적인 문제와 해결법을 다룹니다. 특히 Docker 컨테이너에서 ServBay 서비스 접근 및, ServBay를 활용한 Docker 컨테이너 내 앱의 리버스 프록시 설정에 초점을 맞춥니다.

Q1: ServBay가 내 시스템의 `hosts` 파일을 수정하는 이유는 무엇인가요? 이를 막을 수 있나요?

ServBay는 시스템 hosts 파일에 항목(예: mysite.servbay.demo 127.0.0.1)을 추가하여 여러분이 정의한 로컬 도메인(mysite.servbay.demo 등)으로 쉽게 개발 사이트에 접속할 수 있게 합니다. 실제로 이런 사이트들은 로컬의 127.0.0.1에서 서비스됩니다.

그러나 Docker의 구조상, macOS 호스트의 hosts 파일을 컨테이너가 읽어 들이게 되면 mysite.servbay.demo가 127.0.0.1로 해석되어 Docker에서 잘못된(자신의 컨테이너 내부) 서비스에 연결하게 됩니다.

핵심 원리:

ServBay에서 새로운 웹사이트를 만들고 도메인(예: example.servbay.demo)을 지정하면, 자동으로 해당 도메인을 127.0.0.1로 지정합니다.
이는 로컬 친화적 도메인 접속을 구현하는 일반적인 방법입니다. 만약 hosts 파일 수정이 없다면, 오직 http://127.0.0.1:PORT 형태로만 사이트 접속이 가능하며, 커스텀 도메인 주소는 쓸 수 없습니다.

막을 수 있나요?

이론적으로 ServBay가 추가한 항목을 hosts 파일에서 삭제할 수 있지만, 그렇게 하면 ServBay가 제공하는 도메인으로 웹사이트 접속이 불가능해집니다. 이는 ServBay가 지향하는 편리한 로컬 개발 환경 제공 취지와 어긋납니다. ServBay가 자동으로 hosts 파일을 관리하는 것은 로컬 사이트 생성 및 접속 절차를 한층 간편하게 하려는 핵심 기능입니다.
만약 특정 도메인의 hosts 항목 관리를 원하지 않는다면, 해당 도메인으로는 ServBay에서 웹사이트 생성을 하지 않는 것이 좋습니다.

대부분의 로컬 개발 시나리오에서 ServBay의 자동 hosts 파일 관리 기능은 개발 프로세스를 크게 단축·간소화해줍니다.

Q2: 내 Docker 컨테이너가 macOS 호스트에서 운영되는 ServBay 웹사이트(예: `mysite.servbay.demo`)에 도메인으로 접근하려면?

많은 분들이 갖는 요구이지만, 올바른 처리가 필요합니다.
ServBay에서 macOS 호스트에 웹사이트를 운영한다면(mysite.servbay.demo가 호스트에선 127.0.0.1로 해석됨), Docker 내부에서 127.0.0.1은 컨테이너 자신의 주소를 의미합니다.

잘못된 방법: URL에서 직접 host.docker.internal을 도메인명으로 사용

Docker Desktop for Mac(및 Windows)에서는 컨테이너가 호스트의 IP로 통신할 수 있게 host.docker.internal이라는 특수 DNS명을 제공합니다.
그러나 웹사이트 접속 시 이 값을 URL에 직접 사용(예: http://host.docker.internal/)하는 것은 권장하지 않습니다.

이 경우 요청의 HTTP 헤더 Host가 host.docker.internal이 되어, ServBay의 웹서버(Caddy 또는 Nginx)는 어떤 사이트를 요청하는 지 식별할 수 없습니다. Host가 mysite.servbay.demo가 아니므로 제대로 요청을 라우팅하지 못하며, 만약 HTTPS 환경이면 SNI(Server Name Indication) 오류도 발생할 수 있습니다. 왜냐하면 SSL 인증서는 mysite.servbay.demo 기준으로 발급되어 있고, host.docker.internal에는 맞지 않기 때문입니다.

올바른 해결법: Docker 컨테이너 시작 시 extra_hosts 지정

컨테이너 내부 앱이 ServBay 사이트의 실제 도메인(mysite.servbay.demo)을 사용해 요청을 보내게 하려면, 컨테이너의 /etc/hosts에 해당 도메인과 호스트 IP를 연결해줘야 합니다. 이건 docker-compose.yml의 extra_hosts나, docker run의 --add-host로 지정할 수 있습니다. 추천 방식은 host-gateway 사용입니다.

docker run 사용 예:
bash
```
docker run --add-host=mysite.servbay.demo:host-gateway ... your_image
```
1
(host-gateway는 Docker 20.10+ 버전에서 호스트 내부 IP로 치환되는 특수값이며, 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"
    # ... 기타 설정

설정 후, 컨테이너 내부 동작:

앱에서 http://mysite.servbay.demo 혹은 https://mysite.servbay.demo로 접속 시, /etc/hosts가 이 도메인을 macOS 호스트 IP로 변환합니다.
요청은 호스트에서 실행 중인 ServBay 웹서버로 들어갑니다.
HTTP Host 헤더가 올바르게 mysite.servbay.demo로 유지되어 ServBay가 정상적으로 요청을 라우팅하고, (HTTPS면) 적합한 SSL 인증서를 제공합니다.

Q3: 내 Docker 컨테이너에서 ServBay가 관리 중인 데이터베이스(MySQL, PostgreSQL 등) 또는 HTTP외의 서비스에 연결하려면?

웹사이트 접속과 달리, 일반 TCP 서비스(데이터베이스 등) 연결은 SNI를 필요로 하지 않아,
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로 연결했다고 가정합시다.
만약 secure.servbay.demo가 ServBay User CA로 발급된 SSL 인증서를 사용한다면, 기본적으로 Docker 컨테이너는 이 CA를 신뢰하지 않아 SSL 핸드셰이크에서 오류가 납니다.

ServBay CA 파일 위치(macOS 호스트):

ServBay User CA 루트 인증서: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
CA 포함 PEM 파일:
- ARM Mac: /Applications/ServBay/package/common/openssl/3.2/cacert.pem
- Intel Mac: /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem

해결 방법 요약:

컨테이너에서 ServBay User CA를 신뢰하는 방법은 여러 가지가 있습니다:

방법 1: 이미지 빌드시 시스템 전체 신뢰(Dockerfile 이용) – CA 전체 시스템 신뢰 필요 시(권장)
방법 2: 컨테이너 실행 시 특정 애플리케이션에만 신뢰(volume+환경변수) – 이미지 수정 없이 일부 앱에만 적용
방법 3: 실행 시 시스템 신뢰(volume+커맨드 재정의) – 빌드 없이 시스템 전체 신뢰 필요시(약간 복잡)

방법 1: 빌드시 시스템 신뢰(Dockerfile 사용)

컨테이너 이미지를 빌드할 때 CA 인증서를 시스템 신뢰 저장소에 추가합니다.

CA 파일 준비: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt를 Dockerfile과 같은 디렉토리에 복사

Dockerfile(DEB/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

Compose 빌드 예시:

yaml

# docker-compose.yml
version: '3.8'
services:
  myapp:
    build:
      context: ./app_service # Dockerfile/CA 파일 포함
      dockerfile: Dockerfile
    extra_hosts: ["secure.servbay.demo:host-gateway"]

방법 2: 컨테이너 실행 시 애플리케이션별 신뢰(volume + env)

이 방법은 CA 파일을 컨테이너에 마운트하고, 애플리케이션 환경변수로 CA 지정합니다.

docker-compose.yml 예시:

yaml

version: '3.8'
services:
  myapp:
    image: some-base-image
    volumes:
      - /Applications/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:
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

사용 중인 앱에 따라 적합한 환경변수를 참조하세요.

방법 3: 컨테이너 실행 시 시스템 전체 신뢰(volume + custom command)

이 방법은 CA 파일을 마운트하고, 컨테이너 시작 시 시스템 신뢰 저장소를 동적으로 갱신합니다. 이미지 빌드 단계가 필요 없지만, 실행 커맨드가 길어질 수 있습니다.

Debian/Ubuntu 계열 예시:

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # update-ca-certificates 지원 이미지
    volumes:
      - /Applications/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 스크립트에서 권한 처리

참고사항:

복잡성: command/entrypoint 변형이 복잡할 수 있으며, 공식 이미지에선 더 복잡해질 수 있습니다.
권한: update-ca-certificates는 대개 root 권한 필요
패키지: ca-certificates와 update-ca-certificates가 설치되어 있어야 하며, 예시 스크립트는 미설치 시 설치
부팅 시간: 매번 시작 시 갱신하는 만큼 부팅 시간 증가
Alpine: Alpine에서는 apk add --no-cache ca-certificates && update-ca-certificates 사용

어떤 방법을 선택할지?

이미지 빌드가 가능한 상황·CA 전체 신뢰가 필요하다면 방법 1이 최적
이미지 수정 없이 특정 앱만 신뢰하도록 하고 싶다면 방법 2가 쉽습니다
빌드 없이 시스템 전체 신뢰 필요하다면 방법 3을 선택

공용 CA(예: Let's Encrypt) 인증서 쓸 때는?
ServBay가 ACME 방식으로 Let's Encrypt 같은 공용 CA 인증서를 받았다면, 대부분의 도커 기본이미지에 이미 해당 루트 CA가 있으므로 별도 조치가 필요 없습니다.

Q5: Docker 컨테이너에서 실행 중인 앱에 ServBay 도메인을 부여하고 리버스 프록시하려면?

Docker 컨테이너에 앱(Node.js 등)이 3000 포트 등으로 내부에서 서비스 중이라면, ServBay로 도메인(예: myapp.servbay.demo)을 부여하고 호스트 브라우저에서 접속하고 싶을 수 있습니다. 이와 함께 ServBay의 SSL 관리도 활용 가능합니다.

진행방법:

Docker 컨테이너 실행 시 포트 127.0.0.1에 바인딩해서 호스트로 매핑하기 앱 포트를 macOS 호스트의 포트로 바인딩하고, 필히 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
즉, http://127.0.0.1:3001로 호스트에서 접근 가능
ServBay에 새 사이트 추가 및 리버스 프록시 설정하기
- ServBay 관리 페이지로 이동
- “사이트 추가” 클릭
- 도메인: 예) myapp.servbay.demo 입력
- 사이트 유형: “리버스 프록시” 선택
- IP 주소: 127.0.0.1 입력
- 포트: 위 예시에서 docker 컨테이너가 사용한 호스트 포트(3001) 입력
- “저장” 또는 “추가” 클릭
(선택) SSL 설정 사이트 추가 후 설정 메뉴에서 SSL 활성화 가능.
ServBay는 ACME로 자동 SSL 신청이나, 직접 CA 선택(ServBay User/Public CA)도 가능.
ServBay가 SSL 종료 처리를 맡고, ServBay→Docker 사이는 일반 HTTP(http://127.0.0.1:3001)로 연결됩니다.
접속 테스트 ServBay 설정이 적용된 후 브라우저에서 http://myapp.servbay.demo
또는(SSL 설정시) https://myapp.servbay.demo로 접속해 봅니다.

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

요약

ServBay는 macOS상 로컬 웹 개발 프로세스를 대폭 단순화해줍니다.
Docker와 결합 사용 시:

Docker 컨테이너에서 ServBay 호스팅 웹사이트 접속:
extra_hosts 또는 --add-host로 도메인을 host-gateway에 매핑해서 Host 헤더 전달 및 SNI 문제 예방
Docker 컨테이너에서 ServBay 데이터베이스/비HTTP 서비스 접속:
서버명에 host.docker.internal 사용이 가장 간단
Docker에서 ServBay User CA 인증서 신뢰 필요:
CA를 이미지에 복사+신뢰 스토어 갱신 필요
ServBay 리버스 프록시로 Docker 앱 도메인 부여:
ServBay에 “리버스 프록시” 사이트로 등록, 127.0.0.1 포트 지정

항상 ServBay의 관련 패키지(웹서버, DB 등)와 Docker 컨테이너가 모두 정확히 구성된 상태에서 실행된다는 점을 확인하세요.

ServBay와 Docker 연동 FAQ (자주 묻는 질문) ​

Q1: ServBay가 내 시스템의 hosts 파일을 수정하는 이유는 무엇인가요? 이를 막을 수 있나요? ​

Q2: 내 Docker 컨테이너가 macOS 호스트에서 운영되는 ServBay 웹사이트(예: mysite.servbay.demo)에 도메인으로 접근하려면? ​

Q3: 내 Docker 컨테이너에서 ServBay가 관리 중인 데이터베이스(MySQL, PostgreSQL 등) 또는 HTTP외의 서비스에 연결하려면? ​

Q4: Docker 컨테이너가 도메인(extra_hosts로 지정함)으로 ServBay의 HTTPS 사이트(ServBay User CA 사용)에 접속할 때, 컨테이너에서 이 CA를 신뢰하게 만드는 방법은? ​

방법 1: 빌드시 시스템 신뢰(Dockerfile 사용) ​

방법 2: 컨테이너 실행 시 애플리케이션별 신뢰(volume + env) ​

방법 3: 컨테이너 실행 시 시스템 전체 신뢰(volume + custom command) ​

Q5: Docker 컨테이너에서 실행 중인 앱에 ServBay 도메인을 부여하고 리버스 프록시하려면? ​

요약 ​

ServBay와 Docker 연동 FAQ (자주 묻는 질문)

Q1: ServBay가 내 시스템의 `hosts` 파일을 수정하는 이유는 무엇인가요? 이를 막을 수 있나요?

Q2: 내 Docker 컨테이너가 macOS 호스트에서 운영되는 ServBay 웹사이트(예: `mysite.servbay.demo`)에 도메인으로 접근하려면?

Q3: 내 Docker 컨테이너에서 ServBay가 관리 중인 데이터베이스(MySQL, PostgreSQL 등) 또는 HTTP외의 서비스에 연결하려면?

Q4: Docker 컨테이너가 도메인(`extra_hosts`로 지정함)으로 ServBay의 HTTPS 사이트(ServBay User CA 사용)에 접속할 때, 컨테이너에서 이 CA를 신뢰하게 만드는 방법은?

방법 1: 빌드시 시스템 신뢰(Dockerfile 사용)

방법 2: 컨테이너 실행 시 애플리케이션별 신뢰(volume + env)

방법 3: 컨테이너 실행 시 시스템 전체 신뢰(volume + custom command)

Q5: Docker 컨테이너에서 실행 중인 앱에 ServBay 도메인을 부여하고 리버스 프록시하려면?

요약