배포의 세계 — GitHub Pages부터 Cloudflare까지

 

코드를 로컬에서 돌리는 것과 세상에 공개하는 것 사이에는 생각보다 넓은 간극이 있다. 배포는 단순히 파일을 서버에 올리는 게 아니라, 인프라 아키텍처를 결정하는 일이다.

사이드 프로젝트의 배포 옵션들

프론트엔드 프로젝트를 배포할 수 있는 선택지는 여러 가지다. Vercel, Netlify, GitHub Pages, Cloudflare Pages 등. 각각 장단점이 뚜렷하다.

Vercel은 Next.js 팀이 만든 플랫폼답게 React 프로젝트 배포에 최적화되어 있다. 서버리스 함수도 제공하고, 프리뷰 배포도 자동으로 해준다. 하지만 무료 티어에 상업적 사용 제한이 있고, 대역폭 한도도 있다.

Netlify도 비슷한 포지션이다. 빌드 자동화와 서버리스 함수, 폼 처리 등 편의 기능이 많다. 무료 티어가 넉넉한 편이지만, 빌드 시간에 월별 한도가 있다.

GitHub Pages는 가장 단순하다. GitHub 저장소에 정적 파일을 올리면 끝이다. 서버리스 함수가 없고, 빌드 자동화도 GitHub Actions를 직접 설정해야 한다. 하지만 완전 무료이고, 제한이 거의 없다.

GitHub Pages를 선택한 이유

결론부터 말하면 GitHub Pages를 선택했다. 이유는 세 가지다.

첫째, 완전 무료다. 대역폭 한도가 월 100GB로 넉넉하고, 사이트 크기 제한도 1GB까지다. 사이드 프로젝트로서는 도달하기 어려운 수치다.

둘째, 단순하다. 빌드된 정적 파일을 특정 브랜치에 푸시하면 배포가 완료된다. 별도의 계정 설정이나 플랫폼 학습이 필요 없다. 이미 GitHub을 쓰고 있으니 추가 도구가 하나도 없다.

셋째, React SPA에 충분하다. 타로 마스터는 정적 사이트다. 서버 사이드 로직이 없고, API 호출은 Cloudflare Workers가 담당한다. 정적 파일 호스팅만 하면 되는 상황에서 Vercel이나 Netlify의 고급 기능은 필요 없었다.

GitHub Pages의 단점도 있다. SPA 라우팅 처리를 위해 404.html 트릭을 써야 하고, 빌드 자동화를 직접 구성해야 한다. 하지만 이 정도는 감수할 만했다.

Cloudflare Workers: API의 집

프론트엔드는 GitHub Pages에서 해결됐지만, AI 해석 API를 위한 서버가 필요했다. Part 12에서 다뤘듯이 Cloudflare Workers가 그 역할을 맡는다.

Cloudflare Workers의 핵심 장점은 엣지 컴퓨팅이다. 전 세계 수백 개의 데이터센터에서 코드가 실행되므로, 사용자 위치에 관계없이 빠른 응답을 얻을 수 있다. 한국에서 접속하면 서울이나 도쿄 데이터센터에서 실행되고, 미국에서 접속하면 가까운 미국 데이터센터에서 실행된다.

무료 티어의 하루 100,000건 제한도 사이드 프로젝트에서는 사실상 무제한이다. 초당 약 1.15건의 요청을 24시간 내내 받아야 도달하는 수치다. 분당 100건의 요청이 동시에 들어오더라도, 하루 총량으로는 여유가 있다.

Workers의 코드 배포도 간단하다. Wrangler CLI로 한 줄 명령이면 전 세계 엣지에 배포가 완료된다. 로컬에서 테스트하는 것도 wrangler dev 명령으로 가능하다.

빌드 파이프라인의 설계

배포 자동화의 핵심은 빌드 파이프라인이다. 코드를 푸시하면 자동으로 빌드, 검증, 배포까지 이어지는 흐름을 만들어야 한다.

타로 마스터의 빌드 파이프라인은 네 단계로 구성된다. typecheck, vite build, sitemap, prerender. 각 단계가 순서대로 실행되며, 하나라도 실패하면 배포가 중단된다.

첫 번째 단계는 TypeScript 타입 체크다. 런타임 에러를 사전에 잡아준다. 타입 에러가 있는 코드가 프로덕션에 배포되는 일을 방지한다.

두 번째 단계는 Vite 빌드다. TypeScript를 JavaScript로 변환하고, 번들링하고, 최적화한다. 코드 스플리팅, 트리 셰이킹, 에셋 해싱 등이 이 단계에서 처리된다.

세 번째 단계는 사이트맵 생성이다. Part 13에서 다뤘듯이, 라우트 설정에서 전체 URL 목록을 추출해서 sitemap.xml을 생성한다.

네 번째 단계는 프리렌더링이다. 빌드된 정적 파일을 헤드리스 브라우저로 렌더링해서, 각 페이지의 완성된 HTML을 생성한다. SEO를 위해 필수적인 단계다.

이 네 단계가 모두 성공하면, 결과물이 GitHub Pages에 배포된다. GitHub Actions를 사용해서, main 브랜치에 푸시할 때마다 이 파이프라인이 자동으로 실행되도록 설정했다.

커스텀 도메인과 HTTPS

GitHub Pages는 기본적으로 username.github.io/repository 형태의 URL을 제공한다. 이것도 나쁘지 않지만, 프로젝트의 정체성을 위해 커스텀 도메인을 연결하는 것이 좋다.

도메인을 구매하고 DNS 설정에서 GitHub Pages의 IP를 가리키도록 A 레코드를 설정했다. CNAME 파일을 저장소에 추가하면, GitHub Pages가 자동으로 커스텀 도메인을 인식한다.

HTTPS도 자동으로 제공된다. GitHub Pages가 Let's Encrypt 인증서를 자동으로 발급하고 갱신해준다. 별도의 SSL 인증서 관리가 필요 없다. 이건 무료 호스팅 서비스의 큰 장점이다.

총 비용 $0의 해부

이 프로젝트의 인프라 비용을 정리해보자.

정적 호스팅은 GitHub Pages로 무료다. API 서버는 Cloudflare Workers로 무료다. AI 추론은 Groq API(무료 티어) 또는 Cloudflare Workers AI(무료 할당)로 무료다. 도메인 비용만 연간 소액이 발생하지만, 이것도 무료 도메인을 사용하면 제로로 만들 수 있다.

서버 비용 제로. 이것이 2020년대 사이드 프로젝트의 현실이다. 10년 전이었다면 AWS EC2 인스턴스를 빌려야 했고, 월 수천 원에서 수만 원의 비용이 발생했을 것이다. 지금은 무료 티어의 조합만으로 프로덕션 수준의 서비스를 운영할 수 있다.

무료 인프라의 한계와 트레이드오프

물론 공짜 점심은 없다. 무료 인프라에는 분명한 한계가 있다.

GitHub Pages는 정적 파일만 서빙할 수 있다. 서버 사이드 렌더링, 데이터베이스 연결, 파일 업로드 같은 동적 기능은 불가능하다. 이런 기능이 필요하면 별도의 서비스를 결합해야 한다.

Cloudflare Workers의 무료 티어는 CPU 시간에 제한이 있다. 요청당 10ms의 CPU 시간이 주어지는데, 복잡한 연산을 수행하기에는 빠듯할 수 있다. API 프록시처럼 단순한 요청 전달에는 충분하지만, 무거운 비즈니스 로직을 실행하기에는 부족하다.

스케일링에 대한 불안감도 있다. 갑자기 트래픽이 폭증하면 무료 할당량을 초과해서 서비스가 중단될 수 있다. 유료 전환 계획을 미리 세워두는 것이 현명하다.

하지만 이런 한계는 "좋은 문제"다. 무료 티어의 한계에 도달했다는 것은 프로젝트가 성공하고 있다는 뜻이다. 트래픽이 없는 프로젝트에서 인프라 비용을 걱정하는 것은 집을 짓기도 전에 가구 배치를 고민하는 것과 같다.

사이드 프로젝트의 첫 번째 목표는 "세상에 내놓는 것"이다. 인프라 비용 때문에 프로젝트를 시작하지 못하는 일은 이제 없어야 한다. 무료 인프라로 시작하고, 성장하면서 투자하면 된다.

다음 편 예고

배포까지 완료되면서 타로 마스터가 세상에 공개됐다. 하지만 진짜 도전은 여기서부터다. Part 16에서는 실제 사용자 피드백을 받고, 예상하지 못했던 문제들을 마주하며, 프로젝트를 개선해나가는 이야기를 다룬다.