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

ServBay는 macOS와 Windows를 지원하는 로컬 웹 개발 환경으로, 다양한 언어와 기술 스택을 지원합니다. 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)의 접근 가능한 포트로 노출되어야 합니다.

예를 들어 내부의 Nginx가 80번 포트를 사용한다면, 아래와 같이 호스트의 8080 포트를 80번 포트로 매핑해서 컨테이너를 실행할 수 있습니다.

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

이 예시에서 Docker 컨테이너 my-nginx-servbay 내부의 Nginx는 80번 포트를 듣고 있지만, -p 8080:80 옵션으로 호스트의 8080 포트에 연결됩니다. ServBay는 호스트의 8080 포트로 연결해야 합니다.

실제 애플리케이션이나 Dockerfile에 따라 컨테이너 내부 서비스의 포트가 올바르게 리스닝되고, 해당 포트가 호스트로 매핑되어 있는지 꼭 확인하세요.

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

macOS 응용 프로그램 폴더에서 ServBay 아이콘을 찾아 더블 클릭해서 관리 인터페이스를 엽니다.

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

ServBay를 열면 메인 화면이 나타납니다. 왼쪽 내비게이션 메뉴에서 웹사이트 항목을 클릭하세요. 이곳에서 이미 추가된 로컬 웹사이트를 관리하거나 설정할 수 있습니다.

설명: 왼쪽 내비게이션의 "웹사이트"를 클릭해 관리 페이지로 진입합니다.

4단계: 새 웹사이트 추가

웹사이트 관리 페이지 하단에서 + 버튼을 볼 수 있습니다. 클릭하면, 오른쪽 영역에 새 웹사이트를 설정할 수 있는 입력 폼이 펼쳐집니다.

설명: 페이지 하단의 "+" 버튼을 클릭해 새 웹사이트를 추가합니다.

5단계: 웹사이트 설정 입력

새롭게 열린 웹사이트 설정 폼에서 다음 핵심 정보를 입력해야 합니다.

1. 이름 (Name): 관리하기 쉬운 이름을 지정하세요. 예: Docker Nginx Demo. 이 이름은 ServBay 내부 관리용입니다.
2. 도메인 (Domain): 브라우저에서 접근할 Docker 컨테이너 웹사이트의 도메인을 입력합니다. .servbay.demo와 같은 서픽스를 사용하여 공용 도메인과 충돌을 피하는 것이 좋으며, 예를 들어 docker.servbay.demo 등이 적합합니다. ServBay가 시스템 호스트 파일에 자동으로 등록해 127.0.0.1로 연결하게 됩니다.
3. 프로토콜 (Protocol): 웹사이트가 사용할 프로토콜을 선택하세요. 기본값인 HTTP/HTTPS를 유지하면 됩니다. ServBay는 HTTP(80)와 HTTPS(443)를 모두 리스닝하며 SSL 설정에 따라 처리합니다.
4. SSL 인증서 요청 방식 (SSL Certificate Request Method): ServBay CA 선택을 추천합니다. ServBay는 자체적으로 신뢰할 수 있는 SSL 인증서를 생성·관리해줍니다. ServBay Public CA를 시스템 키체인에 추가하면, 브라우저에서 이 인증서를 신뢰하여 HTTPS 개발·테스트가 편리해집니다. 필요시 ACME(Let's Encrypt 등)나 Custom(직접 인증서 사용)도 선택할 수 있습니다.
5. 웹사이트 유형 (Website Type): 【중요】 리버스 프록시 (Reverse Proxy)를 선택합니다. 도메인 진입점으로 ServBay가 동작하며, 요청을 지정된 백엔드 서비스 주소로 포워딩하게 됩니다.
6. IP 주소 (IP Address): Docker 컨테이너 서비스가 리스닝하는 호스트 IP를 입력합니다. 일반적으로 로컬 루프백 주소 127.0.0.1을 사용합니다.
7. 포트 (Port): Docker 컨테이너 서비스가 호스트에 노출하고 있는 포트 번호를 입력합니다. 이는 docker run -p <호스트 포트>:<컨테이너 포트> 옵션의 <호스트 포트>에 해당합니다. 예를 들어 -p 8080:80을 사용했다면, 여기엔 8080을 입력합니다.

설명: Docker 리버스 프록시 웹사이트 설정 정보를 입력합니다.

6단계: 입력 완료 및 설정 저장

필요 정보를 모두 입력한 뒤 폼 하단의 추가(Add) 버튼을 클릭합니다.

ServBay는 입력한 정보로 웹 서버(Caddy 또는 Nginx 등)의 리버스 프록시 규칙을 자동으로 추가해주며, 시스템 호스트 파일도 적절히 업데이트합니다.

설정이 성공적으로 저장되면 잠시 적용 시간이 소요될 수 있으며, 바로 도메인에 접속해 사이트를 테스트할 수 있습니다.

7단계: 웹사이트 접속 및 빠른 액션 활용

설정 완료 후 관리 페이지로 돌아가면 새로 추가된 웹사이트가 표시됩니다. 상태가 "실행중"임을 확인하세요.

브라우저에서 설정한 도메인 (예: http://docker.servbay.demo 또는 https://docker.servbay.demo)을 열면, 올바르게 설정된 경우 ServBay가 요청을 Docker 컨테이너 서비스로 전달하고 컨테이너의 웹페이지가 표시됩니다.

해당 사이트 항목에는 다양한 빠른 액션 버튼도 제공됩니다:

1. IDE로 웹사이트 루트 열기: (리버스 프록시 타입 사이트의 경우, 이 버튼은 ServBay 설정폴더 등으로 연결될 수 있으며, 실제 동작은 버전·설정에 따라 다릅니다)
2. 브라우저에서 사이트 열기: 한 번에 새 탭에서 해당 URL을 열 수 있는 버튼.
3. 사이트 로그 확인: ServBay가 기록한 접속 및 오류 로그를 보는 기능으로, 디버깅에 유용합니다.
4. 웹사이트 일시 정지 및 실행: ServBay 리버스 프록시 설정을 통해 사이트 임시 비활성/활성화.
5. 웹사이트 삭제: 해당 사이트 설정을 ServBay에서 삭제합니다.

설명: ServBay 웹사이트 목록에서 제공되는 빠른 액션 버튼.

참고사항 및 베스트 프랙티스

• Docker 컨테이너 상태: 대상 Docker 컨테이너가 항상 실행 중이어야 요청이 정상 전달됩니다.
• 포트 매핑: Docker의 포트 매핑(-p 옵션)과 ServBay에 입력한 포트 번호가 일치하는지, 해당 포트가 호스트에서 다른 프로그램에 점유되어 있지 않은지 꼭 확인하세요.
• 방화벽: macOS 방화벽 설정을 점검해 ServBay가 사용하는 포트(기본 80, 443) 및 Docker가 노출한 호스트 포트가 차단되지 않았는지 확인하세요.
• Docker 네트워크 모드: 대개 기본 bridge 네트워크에 -p로 포트 매핑하는 것이 가장 간단합니다. host 모드를 사용하는 경우, ServBay가 컨테이너 내부 포트에 직접 접근하므로(예: 80번), 포트 충돌에 주의하세요.
• ServBay CA: HTTPS 개발을 위해 ServBay Public CA 설치를 권장합니다. ServBay가 발급한 로컬 인증서를 브라우저에서 신뢰하게 되어, 보안 경고 없이 편리하게 개발할 수 있습니다.

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

Q: 웹사이트 추가 후 접속이 안 되고, 브라우저에서 연결 오류나 시간 초과가 발생합니다.

A: 아래 순서대로 확인하세요:

1. 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 컨테이너 로그는 docker logs <컨테이너ID 또는 이름>으로 확인할 수 있습니다.
5. ServBay 로그 확인: 로그 아이콘을 클릭해 ServBay의 접속/오류 로그를 확인하면, 프록시 실패 등 상세 원인을 알 수 있습니다.
6. 호스트 파일 확인: 대부분 자동 처리되지만 /etc/hosts 파일에서 도메인이 127.0.0.1로 제대로 연결되는지 수동으로도 확인하세요.
7. 방화벽 확인: ServBay, Docker에서 사용하는 포트가 방화벽에 차단되어 있지 않은지 점검하세요.

Q: ServBay로 Docker 컨테이너 자체를 직접 관리할 수 있나요?

A: ServBay는 로컬 웹 서비스, 데이터베이스, 언어 환경 관리 및 트래픽을 백엔드 서비스(Docker 컨테이너 포함)로 전달하는 기능을 제공합니다. 컨테이너의 생성/실행/종료/이미지 빌드 등 라이프사이클 전체 관리는 별도로 Docker 명령어 또는 Docker Desktop에서 직접 진행해야 합니다.

Q: ServBay CA란 무엇이고, 왜 설치해야 하나요?

A: ServBay CA(인증기관)는 로컬 HTTPS 개발을 위해 ServBay에서 제공하는 인증서 관리 시스템입니다. ServBay User CA가 로컬 웹사이트의 SSL 인증서를 발급하며, ServBay Public CA는 이 User CA의 루트 인증서 역할을 합니다. ServBay Public CA를 시스템 키체인에 추가하면, OS와 브라우저가 ServBay User CA의 인증서를 신뢰하여, 로컬 ServBay HTTPS 사이트 접속 시 "보안 연결 아님" 경고가 사라집니다. 실제 환경과 유사한 HTTPS 개발/테스트에 매우 중요합니다.

결론

ServBay에서 Docker 컨테이너 기반 웹사이트를 추가하는 과정은 효율적이고 유연하며, ServBay가 트래픽과 도메인 관리를 담당하는 로컬 개발 허브 역할을 하고, Docker가 애플리케이션 환경을 격리·실행하는 구조입니다. 간단한 리버스 프록시 설정으로 다양한 Docker 프로젝트를 ServBay 워크플로우에 쉽게 통합할 수 있습니다. 본문의 단계와 참고 사항을 따르면 Docker 기반 로컬 사이트를 손쉽게 구축하고 운영할 수 있습니다.