Hugo로 매뉴얼 만들기 #4 Cloudflare Pages로 배포하고 도메인 연결하기

프레임워크 Hugo Documentation Static Site
4 분 소요

#3까지 오면 로컬에서 보기 좋은 문서가 갖춰집니다. 하지만 localhost는 나만 볼 수 있습니다. 이번 글에서는 이 문서를 누구나 주소로 접속할 수 있게 내보냅니다.

이번 시리즈는 Hugo로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지
  • #2 사이드바와 검색 — 문서의 정보 구조 잡기
  • #3 콘텐츠 작성 — 코드블록, Mermaid, 콜아웃
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기 ← 이번 글
  • #5 다국어와 버전 관리
  • #6 유지보수 — 검색 색인, 접근성, 문서 문화

이번 글은 GitHub에 올리고, Cloudflare Pages에 연결해 빌드를 잡고, 커스텀 도메인을 붙이는 데까지 다루겠습니다.

정적 사이트는 어디에 올리나 #

Hugo가 만든 결과물은 HTML, CSS, JS 정적 파일 묶음입니다. 서버에서 돌아가는 코드가 없으니, 파일을 그대로 받아 주는 호스팅이면 충분합니다. 이 글에서는 Cloudflare Pages를 씁니다. 무료 구간이 넉넉하고, Git 저장소에 푸시하면 자동으로 빌드해 배포하며, 전 세계 CDN과 HTTPS가 기본으로 딸려 옵니다.

1. GitHub에 올리기 #

Cloudflare Pages는 Git 저장소를 바라보며 빌드합니다. 먼저 문서를 GitHub에 올립니다. 빌드 결과물과 캐시는 저장소에 넣지 않도록 .gitignore부터 만듭니다.

.gitignore 
/public/
/resources/_gen/
.hugo_build.lock

그다음 저장소를 초기화해 푸시합니다.

GitHub에 올리기 
git init
git add .
git commit -m "docs: 첫 문서"
git branch -M main
git remote add origin https://github.com/내계정/my-docs.git
git push -u origin main

2. Cloudflare Pages에 연결 #

Cloudflare 대시보드에서 Workers & Pages → Create → Pages → Connect to Git로 방금 올린 저장소를 선택합니다. 그다음 빌드 설정을 다음과 같이 지정합니다.

항목값
프레임워크 프리셋Hugo
빌드 명령hugo --gc --minify
빌드 출력 디렉터리public

Save and Deploy를 누르면 첫 배포가 시작되고, 끝나면 프로젝트이름.pages.dev 주소가 생깁니다. 이후로는 main에 푸시할 때마다 자동으로 다시 빌드됩니다.

3. 빌드 환경 — Hugo 버전과 Go #

배포가 한 번에 안 되면 십중팔구 빌드 환경 문제입니다. 두 가지를 확인합니다.

첫째, Hugo 버전입니다. 환경 변수에 HUGO_VERSION을 지정해 로컬과 같은 버전으로 맞춥니다. Hextra처럼 내장 에셋 처리를 쓰는 테마는 Extended 버전이 필요한데, Cloudflare는 HUGO_VERSION으로 지정한 버전의 Extended 빌드를 설치합니다.

환경 변수값(예시)
HUGO_VERSION0.140.0

둘째, Go입니다. #1에서 봤듯 Hextra는 Hugo Modules로 배포되고, 모듈을 내려받으려면 Go가 필요합니다. Cloudflare 빌드 이미지에는 Go가 들어 있어 대개 그대로 되지만, 모듈을 못 받아 빌드가 멈춘다면 GO_VERSION 환경 변수를 추가해 버전을 명시하면 해결됩니다.

4. 커스텀 도메인 연결 #

pages.dev 주소 대신 직접 산 도메인을 붙입니다. Pages 프로젝트의 Custom domains → Set up a domain에서 도메인을 입력합니다.

도메인을 이미 Cloudflare에서 관리 중이라면 DNS 레코드가 자동으로 추가됩니다. 다른 곳에서 관리한다면, 그쪽 DNS에 다음 레코드를 직접 넣습니다.

DNS 레코드 (하위 도메인) 
유형    이름     값
CNAME   docs     프로젝트이름.pages.dev

루트 도메인(example.com)에 바로 붙이려면 CNAME 평탄화를 지원하는 Cloudflare DNS를 쓰는 편이 가장 깔끔합니다. 연결이 끝나면 HTTPS 인증서는 Cloudflare가 자동으로 발급하고 갱신합니다.

한 가지 함정 — 발행일과 예약 #

배포가 되고 나면 한 번쯤 부딪히는 문제가 있습니다. 미래 날짜로 적어 둔 글이 그날이 되어도 안 보이는 경우입니다.

Hugo는 기본적으로 미래 날짜 글을 빌드에서 제외합니다. 그리고 Cloudflare Pages는 푸시가 있을 때만 다시 빌드합니다. 둘을 합치면, 미래 날짜로 예약해 둔 글은 날짜가 되어도 저절로 공개되지 않습니다. 그날 새 빌드가 돌지 않기 때문입니다. 예약 발행이 꼭 필요하다면 매일 한 번 빌드를 트리거하는 장치(예약된 배포 훅)를 따로 둬야 합니다. 그게 부담이라면, 글을 쓸 때마다 그날 날짜로 발행하는 편이 단순하고 사고가 없습니다.

마무리 #

이번 글에서는 문서를 GitHub에 올리고, Cloudflare Pages에 연결해 빌드를 잡고, 커스텀 도메인까지 붙였습니다. 이제 문서는 진짜 주소를 갖고 인터넷에 떠 있습니다.

다음 편에서는 다국어와 버전 관리를 다룹니다. 하나의 문서를 여러 언어로 제공하고, 제품 버전이 올라갈 때 옛 문서를 어떻게 함께 유지할지 정리하겠습니다.

X