ServBay에서 Docker 컨테이너 기반 웹사이트 추가 및 구성하기

ServBay는 macOS에 최적화된 로컬 웹 개발 환경으로, 다양한 언어 및 기술 스택을 지원합니다. ServBay 내장 소프트웨어 패키지(예: PHP, Node.js, Python, Go, Java, 데이터베이스 등)로 직접 사이트를 구동할 수 있을 뿐 아니라, Docker 컨테이너를 활용해 자신의 웹사이트나 서비스를 별도로 실행하고 관리할 수도 있습니다. 이러한 방식은 환경 격리 및 일관성을 보장하며, 특정 환경이나 의존성이 필요한 프로젝트에 이상적입니다.

이 문서에서는 ServBay에서 Docker 컨테이너를 통해 웹사이트를 추가하는 방법과, ServBay의 리버스 프록시 기능을 활용한 로컬 개발 프로세스 통합 절차를 상세히 안내합니다.

개요

ServBay를 리버스 프록시로 설정하면 특정 도메인으로 들어오는 요청을 Docker 컨테이너 내부 서비스 포트로 전달할 수 있습니다. ServBay가 진입 트래픽(예: HTTPS 인증서, 도메인 해석 등)을 담당하고, Docker 컨테이너는 애플리케이션 실행에 집중합니다. 이 패턴은 ServBay의 편리한 관리 인터페이스와 Docker의 강력한 컨테이너화 기능을 모두 활용할 수 있게 해줍니다.

아래 단계에서는 ServBay에서 Docker 서비스를 기반으로 한 웹사이트를 추가 및 구성하는 전체 과정을 안내합니다.

사전 준비 사항

시작 전에, 다음 조건을 충족했는지 확인하세요:

1. ServBay 설치 및 실행: macOS에 ServBay를 성공적으로 설치하고 실행 중이어야 합니다.
2. Docker 설치 및 실행: macOS에 Docker Desktop 또는 기타 Docker 환경을 설치하고 Docker 서비스가 실행 중이어야 합니다.
3. Docker 이미지 및 컨테이너 준비: 웹사이트 또는 애플리케이션이 포함된 Docker 이미지를 빌드 또는 Pull한 상태이며, 해당 이미지를 이용해 컨테이너를 실행할 수 있어야 합니다.

사이트 추가 상세 절차

1단계: Docker 컨테이너 준비 및 실행

우선, Docker 컨테이너가 실행 중이며 내부 서비스(예: 웹 서버)가 특정 포트를 통해 정상적으로 동작하고, Docker의 포트 매핑을 이용해 호스트(macOS)의 사용 가능한 포트로 노출되었는지 확인하세요.

예시로, 내부적으로 80번 포트를 사용하는 Nginx 컨테이너가 있다면, 다음 명령으로 호스트의 8080 포트를 컨테이너의 80포트와 매핑할 수 있습니다:

docker run -d --name my-nginx-servbay -p 8080:80 nginx

이 예제에서 Docker 컨테이너 my-nginx-servbay 내부의 Nginx 서비스는 80 포트에서 대기합니다. -p 8080:80 인자를 통해 컨테이너의 80 포트가 호스트의 8080 포트에 매핑된 것입니다. ServBay는 이 호스트 8080 포트로 연결해야 합니다.

자신의 애플리케이션 및 Dockerfile 설정에 맞게 컨테이너 내부 서비스가 올바른 포트에서 대기하고, 해당 포트가 호스트로 정확히 매핑되어 있는지 다시 한번 확인해야 합니다.

2단계: ServBay 관리 인터페이스 열기

macOS 응용프로그램 폴더에서 ServBay 아이콘을 찾아 더블 클릭하면 ServBay 관리 화면이 실행됩니다.

3단계: 사이트 관리 페이지로 이동

ServBay를 실행하면 기본 화면이 나타납니다. 좌측 사이드바 메뉴에서 사이트 옵션을 찾아 클릭하세요. 이곳에서 지금까지 추가한 모든 로컬 사이트를 확인하고 설정을 변경할 수 있습니다.

이미지: 왼쪽 네비게이션 바에서 “사이트”를 클릭해 관리 페이지 진입.

4단계: 새 사이트 추가

사이트 관리 페이지 하단에서 + 버튼을 찾을 수 있습니다. 클릭 시, 우측 영역에 신규 사이트 설정 폼이 확장되어 나타납니다.

이미지: 페이지 하단 “+” 버튼 클릭하여 새 사이트 추가.

5단계: 사이트 설정 입력

새롭게 열린 사이트 등록폼에 다음의 주요 정보를 입력해야 합니다:

1. 이름 (Name): 사이트를 쉽게 식별할 수 있는 이름을 입력하세요(예: Docker Nginx Demo). 이 이름은 ServBay 내부에서만 사용됩니다.
2. 도메인 (Domain): 해당 Docker 컨테이너 사이트를 브라우저에서 접속하고자 하는 로컬 도메인을 입력합니다. .servbay.demo와 같은 전용 도메인 접미사를 활용하면 외부 도메인과의 충돌을 방지할 수 있습니다(예: docker.servbay.demo). ServBay가 hosts 파일을 자동으로 수정하여 해당 도메인을 127.0.0.1로 연결합니다.
3. 프로토콜 (Protocol): 지원할 프로토콜을 선택합니다. 기본값인 HTTP/HTTPS를 권장합니다. ServBay는 80(HTTP)과 443(HTTPS) 포트 모두를 리슨하며, SSL 설정에 따라 자동 처리합니다.
4. SSL 인증서 요청 방식 (SSL Certificate Request Method): ServBay CA 선택을 권장합니다. ServBay가 자체적으로 로컬 시스템에서 신뢰받는 SSL 인증서를 생성‧관리합니다. ServBay Public CA를 시스템 키체인에 설치해두면 브라우저에서 로컬 SSL 인증서를 신뢰해 HTTPS 개발 및 테스트가 간편합니다. 필요하다면 ACME(예: Let's Encrypt 인증서용), 또는 Custom(직접 준비한 인증서 사용) 방식도 선택할 수 있습니다.
5. 사이트 유형 (Website Type): 【중요】 리버스 프록시 (Reverse Proxy)를 선택하세요. 이로써 ServBay가 해당 도메인의 트래픽을 지정한 백엔드 서비스(즉, Docker 컨테이너 서비스)로 전달하게 됩니다.
6. IP 주소 (IP Address): Docker 컨테이너 서비스가 리슨하는 호스트의 IP를 입력합니다. 대부분의 로컬 Docker 환경에서는 127.0.0.1(루프백 주소)을 사용합니다.
7. 포트 (Port): Docker 서비스가 호스트에서 노출한 포트 번호를 입력합니다. 즉, docker run -p <호스트포트>:<컨테이너포트> 명령에서 <호스트포트>와 동일해야 합니다. 예를 들어 -p 8080:80을 지정했다면, 이곳에 8080을 입력하면 됩니다.

이미지: Docker 리버스 프록시 사이트 정보 입력 예시.

6단계: 설정 저장 및 완료

모든 필수 정보를 작성했으면 폼 하단의 추가 (Add) 버튼을 클릭하세요.

ServBay가 제출한 정보를 토대로 자체 웹 서버(Caddy 또는 Nginx 등) 설정에 리버스 프록시 규칙을 자동 추가하고, 시스템 hosts 파일도 갱신합니다.

저장이 완료되면 잠깐의 설정 반영 시간이 있을 수 있으며, 이후 곧바로 등록한 도메인 접속 테스트가 가능합니다.

7단계: 사이트 접속 및 빠른 작업 메뉴 활용

설정이 적용된 후 사이트 관리 페이지로 돌아오면, 새 사이트 항목이 리스트에 표시됩니다. 해당 사이트가 “실행 중” 상태인지 확인하세요.

이제 브라우저에서 지정한 도메인(예: http://docker.servbay.demo 또는 https://docker.servbay.demo)으로 접속할 수 있습니다. 모든 내용이 제대로 설정됐다면 ServBay가 요청을 Docker 컨테이너 서비스로 전달하고, 브라우저에서는 컨테이너가 제공하는 페이지를 정상적으로 볼 수 있습니다.

ServBay는 각 사이트 항목마다 편리한 빠른 작업 버튼을 제공합니다:

1. IDE로 사이트 루트 폴더 열기: (리버스 프록시 사이트의 경우 사용이 불가하거나, ServBay 설정 폴더로 연결될 수 있습니다. 실행 방식은 ServBay 버전 및 설정에 따라 다를 수 있습니다.)
2. 브라우저로 사이트 열기: 클릭 한 번으로 새 탭에서 사이트 URL을 바로 확인할 수 있습니다.
3. 사이트 로그 보기: 사이트의 접속 및 에러 로그를 확인해, 디버깅에 큰 도움이 됩니다.
4. 사이트 일시중지/활성화: ServBay 리버스 프록시 동작을 일시적으로 중지하거나 다시 켤 수 있습니다.
5. 사이트 삭제: 해당 사이트의 ServBay 설정을 완전히 삭제합니다.

이미지: ServBay 사이트 리스트의 빠른 작업 아이콘 설명.

유의사항 및 권장 실전 팁

• Docker 컨테이너 상태: 대상 Docker 컨테이너가 항상 실행 중이어야 ServBay가 요청을 정상적으로 전달할 수 있습니다.
• 포트 매핑: Docker의 포트 매핑(-p 옵션) 및 ServBay에 입력한 포트가 정확히 일치하는지, 해당 포트가 호스트에서 다른 프로그램과 충돌하지 않는지 꼼꼼히 확인하세요.
• 방화벽 설정: macOS 방화벽에서 ServBay 사용 포트(기본 80, 443) 및 Docker가 사용하는 호스트 포트에 대한 접근이 차단되어 있지 않은지 확인하세요.
• Docker 네트워크 모드: 대부분의 상황에서는 기본 bridge 모드와 -p 포트 매핑을 사용하는 것이 가장 쉽습니다. 만약 host 모드를 이용한다면 ServBay에서 컨테이너 내부 리슨 포트로 직접 연결하면 되지만(컨테이너가 80포트를 리슨하면 ServBay에 80 입력), host 모드는 포트 충돌 문제가 발생할 수 있습니다.
• ServBay CA: HTTPS 개발에 도움이 되도록 ServBay Public CA를 설치하는 것을 강력 추천합니다. 이를 통해 로컬 인증서가 브라우저에서 신뢰되어, 보안 경고 없이 HTTPS 사이트를 개발하고 테스트할 수 있습니다.

자주 묻는 질문 및 문제 해결 (FAQ)

Q: 사이트를 추가했는데 접속이 되지 않고 브라우저에 연결 오류 또는 타임아웃이 표시됩니다.

A: 다음 순서로 점검해보세요:

1. ServBay 사이트 상태 확인: ServBay 사이트 관리 화면에서 해당 사이트가 “실행 중”인지 확인합니다.
2. Docker 컨테이너 실행 상태 확인: 터미널에서 docker ps 명령으로 대상 컨테이너가 동작 중인지 체크합니다.
3. Docker 포트 매핑 확인: docker ps로 표시되는 컨테이너의 PORTS 항목에서 호스트 포트(예: 0.0.0.0:8080->80/tcp나 127.0.0.1:8080->80/tcp 내의 8080)가 ServBay에 입력한 포트와 일치하는지 확인합니다.
4. Docker 내부 서비스 상태: 컨테이너 내부 웹 서비스(Nginx, Apache, Node 등)가 정상 포트에서 리슨 중이며, 내부 오류는 없는지 체크합니다. 필요시 docker logs <컨테이너ID 또는 이름>으로 로그를 확인하세요.
5. ServBay 로그 확인: 사이트 리스트에서 로그 아이콘을 클릭하여 ServBay의 접속/에러 로그에서 요청 전달 실패 등에 대한 세부 정보를 확인하세요.
6. 시스템 hosts 파일 확인: ServBay가 자동 관리하지만 /etc/hosts에서 도메인 매핑이 제대로 되어 있는지 수동으로도 확인 가능합니다(127.0.0.1로 연결되어야 함).
7. 방화벽 설정: ServBay 사용 포트 및 Docker 호스트 포트에 대한 접근을 방화벽이 차단하지 않는지 점검하세요.

Q: ServBay에서 Docker 컨테이너 자체까지 관리할 수 있나요?

A: ServBay는 로컬 웹 서비스, 데이터베이스, 개발 언어 환경 관리와, 트래픽을 백엔드(예: Docker 컨테이너)로 라우팅하는 역할에 집중합니다. Docker 컨테이너의 생성, 시작, 중지, 이미지 빌드와 같은 전체 라이프사이클 관리는 포함하지 않으므로, 개별적으로 Docker CLI나 Docker Desktop 등을 통해 관리해야 합니다.

Q: ServBay CA란 무엇이며, 왜 설치가 필요한가요?

A: ServBay CA(인증서 발급 기관)는 로컬 HTTPS 개발을 위해 ServBay가 제공하는 인증서 관리 메커니즘입니다. ServBay User CA는 로컬 사이트 SSL 인증서를 발급하고, ServBay Public CA는 이를 신뢰할 수 있도록 하는 루트 인증서 역할을 합니다. 시스템 키체인에 ServBay Public CA를 설치하면 OS와 브라우저에서 ServBay User CA가 서명한 인증서를 신뢰하므로, ServBay가 호스팅하는 HTTPS 사이트 접속 시 “안전하지 않은 연결” 경고가 표시되지 않습니다. 이는 실제 프로덕션 환경을 모방하여 안전하게 로컬 HTTPS 개발/테스트를 하고자 할 때 필수적입니다.

요약

ServBay에서 Docker 컨테이너 기반 웹사이트를 추가하는 것은 효율적이면서도 유연한 개발 환경 구축 방법입니다. ServBay는 로컬 개발의 중심 허브 역할을 맡아 트래픽·도메인 관리를 담당하며, Docker는 애플리케이션 실행 환경의 격리와 재현성을 제공합니다. 간단한 리버스 프록시 설정만으로도 다양한 Docker 기반 프로젝트를 ServBay 워크플로우에 쉽게 통합할 수 있습니다. 본 문서에 나온 단계와 유의사항을 따르면, Dockerized 로컬 웹사이트를 빠르고 안전하게 설정할 수 있습니다.