ngrok으로 로컬 서버를 인터넷에 공개하기

웹 애플리케이션을 개발하다 보면 로컬에서 실행 중인 서버를 외부에서 접속할 수 있게 해야 할 때가 있습니다. 예를 들어, 작업 중인 결과물을 클라이언트나 동료에게 시연해야 하거나, 외부 서비스(예: GitHub, Stripe, Slack)의 웹훅(Webhook)을 테스트해야 하는 경우가 그렇죠.

매번 클라우드 서버에 배포하는 것은 번거롭고 시간도 오래 걸립니다. 공유기 설정을 건드려서 포트 포워딩을 하는 것도 보안상 위험할 수 있고요.

이럴 때 가장 간편하게 사용할 수 있는 도구가 바로 ngrok입니다. ngrok은 로컬 컴퓨터의 포트를 마치 터널을 뚫듯이 외부 인터넷과 연결해주는 터널링 프로그램입니다.

이번 포스팅에서는 ngrok의 설치 방법부터 기본적인 사용법까지 알아보겠습니다.

ngrok 설치

macOS 사용자는 Homebrew를 통해 간단하게 설치할 수 있습니다.

$ brew install ngrok

Windows나 Linux 사용자는 ngrok 공식 홈페이지에서 운영체제에 맞는 압축 파일을 다운로드하여 직접 설치할 수 있습니다.

인증 토큰 설정

ngrok을 사용하려면 먼저 계정을 생성하고 인증 토큰(Authtoken)을 설정해야 합니다. 과거에는 가입 없이도 기본 기능을 사용할 수 있었지만, 최근 보안 정책이 강화되어 인증 토큰 없이는 다음과 같은 에러가 발생하며 실행되지 않습니다.

ERROR:  authentication failed: Usage of ngrok requires a verified account and authtoken.

ERROR:  Sign up for an account: https://dashboard.ngrok.com/signup
ERROR:  Install your authtoken: https://dashboard.ngrok.com/get-started/your-authtoken

ERROR:  ERR_NGROK_4018
ERROR:  https://ngrok.com/docs/errors/err_ngrok_4018

ngrok 대시보드에 로그인하여 자신의 토큰을 확인한 후, 다음 명령어로 등록해줍니다.

$ ngrok config add-authtoken <YOUR_AUTHTOKEN>

이 설정은 한 번만 해주면 되며, 설정 파일에 저장되어 이후에는 자동으로 적용됩니다.

기본 사용법

설치가 완료되었다면 터미널에서 ngrok 명령어를 사용할 수 있습니다. 가장 기본적인 사용법은 HTTP 터널을 여는 것입니다.

예를 들어, 로컬에서 8000번 포트로 웹 서버를 실행하고 있다고 가정해봅시다. 이 서버를 외부에 공개하려면 다음과 같이 입력합니다.

$ ngrok http 8000

그러면 다음과 같은 화면이 나타납니다.

ngrok                                                                       (Ctrl+C to quit)

⚠️ Free Users: Agents ≤3.19.x stop connecting 2/17/26. Update or upgrade: https://ngrok.com/pricing

Session Status                online
Account                       dale (Plan: Free)
Version                       3.3.0
Region                        Japan (jp)
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://1234-567-890.ngrok-free.app -> http://localhost:8000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

여기서 Forwarding 항목에 있는 https://1234-567-890.ngrok-free.app 주소가 바로 외부에서 접속할 수 있는 공개 URL입니다. 이 주소를 통해 전 세계 어디서든 내 컴퓨터의 8000번 포트에서 실행 중인 서버에 접속할 수 있게 됩니다.

웹 인터페이스 활용하기

ngrok을 실행하면 터미널 출력에 Web Interface라는 항목이 있습니다. 브라우저에서 http://127.0.0.1:4040으로 접속하면 매우 유용한 대시보드를 볼 수 있습니다.

이 대시보드에서는 ngrok 터널을 통해 들어오는 모든 요청(Request)과 그에 대한 응답(Response)을 실시간으로 확인할 수 있습니다. 특히 웹훅을 개발할 때, 외부 서비스가 어떤 데이터를 보내는지 헤더와 바디 내용을 상세하게 뜯어볼 수 있어서 디버깅에 큰 도움이 됩니다.

마치며

ngrok은 로컬 개발 환경을 인터넷에 쉽고 빠르게 공유할 수 있게 해주는 필수적인 도구입니다. ngrok 덕분에 개발자들은 네트워크 터널링을 복잡하게 여기지 않고, 직관적으로 이해하고 쉽게 사용할 수 있게 되었습니다.

더 복잡한 설정이나 유료 기능에 대해서는 공식 문서를 참고해 보시기 바랍니다. 이제 복잡한 배포 과정 없이 편하게 로컬 서버를 공유해 보세요!