Docker와 ngrok을 활용한 react-webcam 개발 환경 구축

React

Docker와 ngrok을 활용한 react-webcam 개발 환경 구축

solfa 2025. 4. 18. 15:16

배경 및 문제 상황

React-Webcam 라이브러리를 사용해서 개발을 진행하던 중, 모바일 환경에서 테스트할 때 중요한 문제점을 발견했다.
모바일 브라우저에서 카메라 접근은 보안상의 이유로 HTTPS 프로토콜에서만 허용되기 때문에, 로컬 개발 환경이 기본적으로 사용하는 HTTP로는 모바일 테스트가 불가능했다. 이를 해결하기 위해 HTTPS 접속을 제공하는 ngrok을 사용하게 되었다.

사용 방법은 다음과 같다.

React Webcam 개발 환경 설정 가이드 - ngrok 사용 편

준비사항

Git
Node.js
pnpm (설치 방법: npm install -g pnpm)
ngrok 계정 (https://ngrok.com 에서 가입)

설정 단계

1. 프로젝트 클론하기

git clone https://github.com/Team-GomSun/FE 
cd FE

2. 의존성 설치하기

꼭 클론한 폴더 안에서 작성해주세요! (pnpm 없으면 설치해야 함)

pnpm install

3. 개발 서버 실행

pnpm run dev

실행하면 다음과 같이 뜬다.

4. ngrok 설치

Mac/Linux: brew install ngrok 또는 npm install -g ngrok
Windows: https://ngrok.com/download 에서 다운로드 후 설치

5. ngrok 인증 설정 (처음 한 번만)

ngrok config add-authtoken [YOUR_AUTH_TOKEN]

6. HTTPS 터널 실행

ngrok http 3000

7. 생성된 HTTPS 주소를 사용하여 모바일에서 접속

여기에서 Forwarding 된 주소!

그럼 이렇게 접속이 가능하다!

이렇게 기존 워크플로우는 다음과 같았다.

터미널에서 pnpm run dev 명령어로 개발 서버 실행
별도의 터미널을 열어 ngrok http 3000 명령어 실행해 HTTPS 터널 생성
생성된 ngrok URL을 통해 모바일에서 테스트

이 과정은 번거로울 뿐 아니라, 팀원마다 환경 설정이 달라 일관된 테스트 환경을 유지하기 어려웠다. 게다가 협업을 하게 되는 팀원 분은 pnpm 설치라던지 ngrok 설치 등 번거로운 설치 과정을 겪어야 같은 개발 환경을 구축할 수 있기 때문에 이런 점을 해결하기 위해 도커를 통해 개발 환경 구성을 해보려고 한다.

도커를 통해 개발 환경 구성하기 with ngrok

목표 설정

모바일 환경에서 카메라 테스트가 가능한 HTTPS 개발 환경 구축
팀원 간 일관된 개발 환경 제공
설정 과정 간소화 (최소한의 명령어)

검토한 솔루션은 세 가지가 있었다.

1. 수동 ngrok 설정 문서화 - 위에 쓴 거!!

장점: 추가 도구 없이 바로 적용 가능
단점: 여전히 여러 단계 필요, 환경 일관성 부족

2. 로컬 SSL 인증서 생성

장점: ngrok 의존성 제거, 안정적인 로컬 URL
단점: 모바일 기기에 인증서 설치 필요, 복잡한 설정 - 이건 좀 아니지

3. Docker + ngrok 통합 환경

장점: 일관된 환경, 간소화된 설정, 단일 명령어 실행
단점: Docker 학습 필요, 추가 시스템 자원 사용

채택한 솔루션: Docker + ngrok 통합 환경

Docker와 ngrok을 통합한 개발 환경을 구축하기로 결정했다. 이 방식은 환경 일관성과 설정 간소화라는 목표를 동시에 달성할 수 있었다.

구현 세부사항

개발 환경 구축을 위해 다음 파일들을 작성했다.

Dockerfile: Node.js 및 pnpm 기반 이미지 정의
docker-compose.yml: 애플리케이션과 ngrok 서비스 구성
setup.sh: 환경 변수 설정 및 Docker 실행 자동화
.dockerignore: 불필요한 파일 제외로 빌드 최적화

자세한 코드는 밑에서 확인할 수 있다.

https://github.com/Team-GomSun/FE/pull/6

feat: docker 개발 환경 구성 by ssolfa · Pull Request #6 · Team-GomSun/FE

1️⃣ 어떤 작업을 했나요? (Summary) resolved feat: Docker 개발 환경 구성 및 HTTPS 지원 추가 #5 React-Webcam이 모바일 환경에서 카메라에 접근하기 위해서는 HTTPS 프로토콜이 필수적입니다. 따라서 Docker와

github.com

중요한 의사결정 포인트

1. 왜 Docker를 선택했는가?

팀원마다 Node.js 버전과 패키지 관리자 설정이 달랐고, AI 구현 담당 팀원은 패키지 매니저 설치, ngrok 설치 등 번거로운 환경 설정을 거쳐야 했다. 편한 협업을 위해 Docker를 통한 개발 환경 표준화가 필요했다.

2. 왜 git clone 과정은 도커라이징하지 않았는가?

git 클론 과정까지 도커라이징하는 것도 가능했지만, 이런 접근 방식 대신 '개발자가 직접 git clone 후 setup.sh 실행'하는 방식을 선택한 이유는 다음과 같다.

개발 투명성 : 개발자가 코드를 직접 받아 확인하는 과정이 중요했다.
점진적 도입과 학습 곡선 고려 : 모든 것을 한 번에 도커라이징하면 학습 장벽이 높아질 수 있다. git clone은 개발자들에게 익숙한 작업이므로, 이 부분은 유지하고 환경 설정 부분만 자동화함으로써 도입 장벽을 낮추었다.
개발 환경에서만 도커 필요 : 배포 환경에서 필요한 게 아니라 모바일 테스트를 위한 개발 환경에서만 필요했기 때문에 기존 Git 기반 개발 워크플로우를 그대로 살리면서, 모바일 테스트 환경만 간소화하는 방향으로 접근했다.

이러한 장점이 추가적인 자동화로 얻을 수 있는 편의성보다 더 가치 있다고 판단했다.

3. 왜 Docker Compose를 사용했는가?

단일 Dockerfile만 사용하는 대신 Docker Compose를 도입한 이유는 다음과 같다.

다중 서비스 관리: 개발 서버(Next.js)와 HTTPS 터널링(ngrok)이라는 두 개의 서비스를 분리해 관리할 필요가 있었다.
네트워크 연결 자동화: Compose는 서비스 간 네트워크 연결을 자동 설정해주었다.
단일 명령어 제어: docker-compose up/down 명령어로 전체 환경을 한 번에 제어할 수 있었다.

대안으로 shell 스크립트를 이용해 Docker 명령을 순차적으로 실행하는 방법도 있었지만, 선언적이고 유지보수가 용이한 Compose 방식이 더 적합하다고 판단했다.

사용자 경험 개선

기존 복잡한 설정 과정을:

git clone [저장소URL]
cd [프로젝트폴더]
pnpm install
pnpm run dev
# 새 터미널 열기
ngrok http 3000

다음과 같이 간소화했다:

git clone [저장소URL]
cd [프로젝트폴더]
chmod +x setup.sh
./setup.sh YOUR_NGROK_AUTH_TOKEN

다시 작성한 개발 환경 가이드는 다음과 같다.

React Webcam 개발 환경 설정 가이드 - Docker 사용 편

pnpm, ngrok 등의 불필요한 설치를 피하기 위한 Docker 개발 환경 설정 가이드입니다. 이 가이드는 ReactWebcam 프로젝트를 Docker와 ngrok을 사용하여 HTTPS 환경으로 설정하는 방법을 안내합니다.

사전 준비사항

Docker 설치
- Docker Desktop 설치 (Windows/Mac)
- Linux의 경우 Docker Engine 설치
ngrok 계정 생성 및 인증 토큰 획득
- ngrok 회원가입
- 로그인 후 Your Authtoken 페이지에서 인증 토큰 확인

설치 및 실행 단계

1. 프로젝트 클론하기

git clone <https://github.com/Team-GomSun/FE>
cd FE

2. 환경 변수 설정

.env 파일을 만들어서 환경 변수를 설정해주세요.

# 프로젝트 루트에 .env 파일 생성
echo "NGROK_AUTH_TOKEN=YOUR_NGROK_AUTH_TOKEN" > .env

(YOUR_NGROK_AUTH_TOKEN 부분에 자신의 ngrok 인증 토큰을 입력하세요!)

3. 실행 권한 부여 및 애플리케이션 시작

터미널에 해당 명령어를 입력해주세요.

chmod +x setup.sh
./setup.sh

4. 확인 및 브라우저에서 접속

스크립트가 실행되면 약 10초 후에 다음과 같은 정보가 표시됩니다.

표시된 ngrok URL을 브라우저에서 열거나 모바일 기기에서 접속할 수 있습니다.

========================================
애플리케이션이 다음 URL에서 실행 중입니다:
<https://xxxx-xxx-xxx-xxx-xxx.ngrok-free.app> -> 여기 접속!
========================================

5. 환경 정리

프로젝트 작업을 마친 후 다음 명령어를 통해 환경을 정리해주세요.

docker-compose down

결론 및 교훈

이번 프로젝트를 통해 개발 환경 표준화의 중요성과 Docker의 유용성을 느꼈다. 써보고 싶던 도커 환경 구성을 해봐서 재밌었다.

이 설정은 프로덕션 환경이 아닌 개발 환경에 초점을 맞추고 있으며, Vercel 배포 과정에는 영향을 주지 않는다.

추후에는 프로덕션 환경에 대한 Docker 설정도 고려해볼 수 있을 것이다.

728x90