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)을 실시간으로 확인할 수 있습니다. 특히 웹훅을 개발할 때, 외부 서비스가 어떤 데이터를 보내는지 헤더와 바디 내용을 상세하게 뜯어볼 수 있어서 디버깅에 큰 도움이 됩니다.

Cloudflare Tunnel과 비교하기

ngrok과 비슷한 역할을 하는 도구로 Cloudflare Tunnel도 많이 쓰입니다. 둘 다 로컬 서버를 외부에 공개할 수 있게 해주지만, 실제로는 지향점이 조금 다릅니다. ngrok은 “지금 바로 임시 URL 하나 열기”에 강하고, Cloudflare Tunnel은 “Cloudflare 네트워크를 통해 내 도메인으로 안정적으로 연결하기”에 더 가깝습니다.

Cloudflare Tunnel에도 ngrok처럼 바로 써볼 수 있는 빠른 터널(Quick Tunnel)이 있습니다. cloudflared를 설치한 뒤 로컬 서버가 8000번 포트에서 실행 중이라면 다음 명령어로 공개 URL을 받을 수 있어요.

$ cloudflared tunnel --url http://localhost:8000

이렇게 실행하면 https://random-words-here.trycloudflare.com처럼 trycloudflare.com의 무작위 서브도메인이 만들어집니다. Cloudflare 계정이나 DNS 설정 없이 시작할 수 있다는 점에서는 ngrok과 비슷합니다. 다만 빠른 터널 URL은 임시 주소이고, cloudflared 프로세스를 종료하면 함께 사라집니다.

차이가 커지는 지점은 커스텀 도메인을 붙여서 지속적으로 운영할 때입니다. ngrok에서도 고정 도메인과 고급 기능을 쓸 수 있지만, 보통 플랜 제약을 먼저 고려해야 합니다. 반면 Cloudflare Tunnel은 Cloudflare에 연결된 도메인이 있다면 터널을 만들고 DNS 레코드를 연결해서 app.example.com 같은 주소를 안정적으로 사용할 수 있습니다.

$ cloudflared tunnel create my-tunnel
$ cloudflared tunnel route dns my-tunnel app.example.com

여기서 route dns 명령은 Cloudflare DNS에 CNAME 레코드를 만들어 app.example.com이 해당 터널을 바라보게 합니다. 그리고 ~/.cloudflared/config.yml에서는 그 호스트명으로 들어온 요청을 어떤 로컬 서비스로 넘길지 정합니다.

tunnel: a1b2c3d4-5678-90ab-cdef-1234567890ab
credentials-file: /Users/dale/.cloudflared/a1b2c3d4-5678-90ab-cdef-1234567890ab.json

ingress:
  - hostname: app.example.com
    service: http://localhost:8000
  - service: http_status:404

Cloudflare Tunnel의 장점은 내 서버가 외부 인바운드 포트를 열 필요가 없다는 점입니다. cloudflared가 Cloudflare 쪽으로 먼저 아웃바운드 연결을 만들고, 사용자의 요청은 Cloudflare를 거쳐 이 터널 안으로 전달됩니다. 여기에 Cloudflare의 TLS, DDoS 방어, 방화벽 규칙, Access 정책을 함께 적용할 수 있어서 홈 서버나 내부 대시보드를 오래 열어둘 때 특히 유용합니다.

그렇다고 ngrok의 자리가 없어지는 건 아닙니다. 웹훅 요청을 빠르게 확인하고, 로컬 대시보드에서 요청과 응답을 바로 뜯어보고, 짧은 데모 URL을 만드는 용도라면 ngrok이 여전히 편합니다. 반대로 커스텀 도메인, 여러 서브도메인, 상시 실행, Cloudflare 보안 기능이 중요하다면 Cloudflare Tunnel을 먼저 검토하는 게 좋습니다.

마치며

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

더 복잡한 설정이나 유료 기능에 대해서는 공식 문서를 참고해 보시기 바랍니다.

커스텀 도메인 연결이나 상시 운영이 필요하다면 앞에서 살펴본 Cloudflare Tunnel 쪽이 더 잘 맞을 수 있습니다. 만약 일시적인 터널링이 아니라 여러 기기를 하나의 사설 네트워크로 상시 연결하고 싶다면 Tailscale 활용법도 참고해보세요. 이제 복잡한 배포 과정 없이 편하게 로컬 서버를 공유해 보세요!