🚀 개인 홈페이지 제작부터 도메인 연결까지: 전 과정 따라하기 매뉴얼
이 문서는 Hugo 정적 사이트를 GitHub에 올리고, Cloudflare Pages로 무료 배포한 뒤, 내 도메인(ccumgol.net)으로 서비스하기까지의 전 과정을 초보자가 따라 할 수 있도록 정리한 매뉴얼입니다.
로컬 개발 환경과 프로젝트 구조에 대한 기초는 manual.md를, 이 과정에서 실제로 겪은 문제들은 issue-report.md를 함께 참고하세요.
0. 전체 그림 이해하기
먼저 우리가 만들 시스템의 흐름을 이해해야 합니다.
| 단계 | 구성 요소 | 사용자가 하는 일 | 시스템에서 일어나는 일 | 결과 |
| 1 | 내 컴퓨터 | 글 작성 / 디자인 수정 | 로컬 프로젝트 파일이 변경됨 | 홈페이지 원본 콘텐츠와 디자인이 준비됨 |
| 2 | GitHub | git push 실행 |
코드와 문서가 ccumgol/myweb 저장소에 보관됨 |
변경 이력이 GitHub에 저장됨 |
| 3 | Cloudflare Pages | 별도 서버 관리 없음 | GitHub 저장소를 받아 자동 빌드 후 전 세계에 배포 | 무료 호스팅으로 사이트가 공개됨 |
| 4 | 방문자 | ccumgol.net 접속 |
Cloudflare가 배포된 사이트를 제공 | 방문자가 최신 홈페이지를 봄 |
| 구성 요소 | 역할 | 비용 |
| Hugo | 마크다운 글을 HTML 웹사이트로 변환하는 정적 사이트 생성기 | 무료 |
| GitHub | 코드와 글의 저장소. 버전 관리(수정 이력) 담당 | 무료 |
| Cloudflare Pages | GitHub의 코드를 받아 빌드하고 전 세계에 배포하는 호스팅 | 무료 |
| 커스텀 도메인 | ccumgol.net 같은 나만의 주소 |
도메인 등록비만 |
핵심 원리: 내 컴퓨터에서 git push 한 번이면, 약 40초 뒤 실제 사이트에 자동 반영됩니다. 서버를 사지도, 관리하지도 않습니다.
1. 준비물
- Hugo Extended 버전 설치
- 아래 박스의 내용을 복사해서 Terminal 창에 붙여넣고 실행
- macOS 기준
- Windows 기준
Windows에서는 winget을 사용하는 방법이 가장 간단합니다. Windows 10/11의 PowerShell 또는 터미널을 열고 아래 명령어를 실행합니다.
만약
winget명령어가 작동하지 않는다면, Microsoft Store에서 앱 설치 관리자(App Installer) 를 업데이트한 뒤 다시 시도하세요. - 테마·템플릿에 따라 추가 프로그램이 필요할 수 있음
Hugo 자체는 위 설치만으로 실행할 수 있습니다. 다만 사용하는 테마, 템플릿, 커스터마이징 방식에 따라 아래 프로그램 설치를 요구할 수 있습니다. 설치 전에는 선택한 테마의 공식 문서를 먼저 확인하세요.
프로그램 언제 필요한가 간단 설명 Node.js Tailwind CSS, PostCSS, npm 패키지, 프론트엔드 빌드 도구를 사용하는 테마 웹사이트의 CSS·JavaScript를 빌드하거나 패키지를 설치할 때 사용하는 JavaScript 실행 환경입니다. Python 이미지 처리, 콘텐츠 변환, 자동화 스크립트를 함께 제공하는 템플릿 문서 변환, 파일 일괄 처리, 자동화 작업에 자주 쓰이는 범용 프로그래밍 언어입니다. Go Hugo Modules 방식으로 테마를 설치하거나 관리하는 경우 Hugo가 만들어진 언어입니다. 일반적인 Hugo 실행에는 필요 없지만, Go 모듈 기반 테마 관리에는 필요할 수 있습니다. macOS 설치 예시
Windows 설치 예시
설치 후 아래 명령어로 정상 설치 여부를 확인합니다.
- Git 설치
Git은 내 컴퓨터의 파일 변경 이력을 관리하고, GitHub로 프로젝트를 올릴 때 사용하는 필수 도구입니다.
- macOS에서는 보통 Homebrew 또는 Xcode Command Line Tools를 통해 설치합니다.
- Windows에서는 PowerShell 또는 터미널에서 아래 명령어로 설치할 수 있습니다.
설치 후 터미널을 새로 열고
hugo version,git --version이 모두 정상 출력되면 Hugo와 Git 준비가 끝난 것입니다. - GitHub 계정 (github.com)
- https://github.com 사이트에 접속하여 계정을 생성합니다.
- 아래 Chapter 4 참고
- Cloudflare 계정 (dash.cloudflare.com)
- https://cloudflare.com 또는 https://dash.cloudflare.com 사이트에 접속하여 계정을 생성합니다.
- 아래 Chapter 5 참고
- (선택) 내 도메인. Cloudflare에서 직접 구매하거나, 타사 도메인을 Cloudflare로 이전 가능
2. 프로젝트 구조와 디자인 커스터마이징
이 프로젝트는 Hugo + Blowfish(또는 다른 테마) 테마를 기반으로 하되, 아래 파일들로 디자인을 완전히 커스터마이징했습니다. 테마 원본은 절대 수정하지 않고(서브모듈), 프로젝트 쪽에 같은 경로의 파일을 만들어 덮어쓰는 방식을 씁니다. 이것이 Hugo의 표준 커스터마이징 방법입니다.
디자인 핵심 결정 사항 (왜 이렇게 했나)
- 서체: 제목은 명조(고운바탕), 본문은 Pretendard. 사역자의 진정성이 느껴지는 조합.
- 색상: 회백색(스톤) 바탕에 테라코타(흙빛 주황) 단일 강조색.
custom.css상단에서 Blowfish의 CSS 변수(-color-primary-*)를 덮어써서 사이트 전체(버튼, 링크, 내부 페이지)에 일괄 적용됨. - 홈 화면:
params.toml의[homepage] layout = "custom"설정 → Hugo가layouts/partials/home/custom.html을 홈으로 렌더링. - 주의: 홈 커스텀 HTML에는 Tailwind 클래스 대신 순수 CSS 클래스(
hp-*) 를 사용했습니다. Blowfish는 CSS가 미리 컴파일되어 있어, 테마가 안 쓰는 Tailwind 클래스를 새로 쓰면 스타일이 적용되지 않기 때문입니다. (자세한 내용은 이슈 리포트 6번)
색상이나 문구를 바꾸고 싶다면
| 바꾸고 싶은 것 | 수정할 파일 |
| 강조 색상 | assets/css/custom.css의 --color-primary-* 값들 |
| 홈 화면 문구 | layouts/partials/home/custom.html |
| 사이트 제목, 저자 소개 | config/_default/languages.ko.toml |
| 메뉴 구성 | config/_default/menus.ko.toml |
| 소개/강연/문의 내용 | content/각폴더/index.md |
3. 로컬에서 미리보기
수정할 때마다 실제 사이트에 올리기 전에 내 컴퓨터에서 확인합니다.
- 브라우저에서
http://localhost:1313접속 - 파일을 저장하면 브라우저가 자동 새로고침됩니다 (라이브 리로드)
- 종료는 터미널에서
Ctrl + C - 이미 1313 포트를 다른 프로젝트가 쓰고 있다면:
hugo server --port 1717
4. GitHub에 올리기
4-1. GitHub에서 저장소 만들기
- github.com 로그인 → 우측 상단 + → New repository
- 이름:
myweb, Public 선택, README 등 추가 옵션은 모두 체크 해제 → Create repository
4-2. 로컬 저장소를 GitHub에 연결하고 푸시
4-3. ⚠️ 서브모듈 주의사항
이 프로젝트의 테마(themes/blowfish)는 git 서브모듈입니다. 다른 컴퓨터에서 이 저장소를 받을 때는 반드시:
-recursive없이 받으면 테마 폴더가 비어 있어 빌드가 실패합니다.
왜 서브모듈 명령어가 필요한가?
5. Cloudflare Pages로 배포하기
5-1. Pages 프로젝트 만들기
- dash.cloudflare.com 로그인
- 왼쪽 메뉴 Compute(또는 Workers & Pages) → Workers & Pages 클릭
- 우측 상단 Create application → Pages 탭 → Connect to Git
- GitHub 연결 승인 화면이 뜨면:
- GitHub 로그인 → “Cloudflare Workers & Pages” 앱 설치 화면에서
- Only select repositories →
myweb선택 → Install & Authorize - ⚠️ 이 승인 과정을 중간에 닫아버리면 “Git 연동 끊김” 문제가 생깁니다 (이슈 리포트 2번)
- 저장소 목록에서
ccumgol/myweb선택 → Begin setup
5-2. 빌드 설정 (가장 중요한 부분!)
| 항목 | 입력값 |
| Project name | myweb (사이트 주소가 myweb-xxx.pages.dev가 됨) |
| Production branch | main |
| Framework preset | Hugo |
| Build command | hugo |
| Build output directory | public |
그리고 반드시 환경 변수를 추가해야 합니다:
| 변수 이름 | 값 |
|———–|—–|
| HUGO_VERSION | 0.164.0 |
🚨 왜 필수인가: Cloudflare의 기본 Hugo 버전(0.147.x)은 Blowfish 테마가 요구하는 최소 버전(0.158.0)보다 낮습니다. 이 변수 없이 배포하면
can't evaluate field Locale...같은 에러와 함께 빌드가 100% 실패합니다. 내 컴퓨터의hugo version과 같은 버전을 넣으세요. (이슈 리포트 1번)
프로젝트 생성 후에 추가하려면: 프로젝트 → Settings → Variables and secrets → Add → Type: Text, 이름/값 입력 → Save
- Save and Deploy 클릭
5-3. 배포 확인
- 배포 페이지에서 진행 단계가 보입니다:
initialize → clone repo → build → deploy - 모두 초록 체크가 되고 로그 마지막에 “Success: Your site was deployed!” 가 나오면 성공
https://myweb-xxx.pages.dev주소를 클릭해 사이트 확인- 실패했다면: 해당 배포의 Details → Build log에서 빨간 에러 메시지를 읽으세요. 원인 수정 후 Retry deployment 버튼으로 재시도할 수 있습니다.
5-4. 자동 배포 테스트
설정이 잘 됐는지는 이렇게 확인합니다:
푸시 후 Cloudflare 대시보드의 Deployments 탭에 몇 초 안에 새 배포가 자동으로 나타나야 정상입니다. 나타나지 않으면 Git 연동이 끊긴 것입니다 (이슈 리포트 2번).
6. 커스텀 도메인 연결하기
myweb-xxx.pages.dev 대신 내 도메인으로 서비스하는 단계입니다.
(전제: 도메인이 같은 Cloudflare 계정에 등록되어 있으면 모든 과정이 자동입니다.)
6-1. 기존 사이트 확인 (중요!)
도메인에 이미 다른 사이트(예: 워드프레스)가 연결되어 있다면, 연결 즉시 기존 사이트는 그 주소에서 내려갑니다. 반드시 먼저 확인하고, 복구에 필요한 기존 DNS 값을 기록해 두세요.
- Cloudflare → 해당 도메인 → DNS 메뉴에서 현재
@(A/AAAA)와www레코드 값을 메모/캡처
6-2. 도메인 추가
- Workers & Pages →
myweb프로젝트 → Custom domains 탭 - Set up a custom domain 클릭
ccumgol.net입력 → Continue- “Confirm new DNS record” 화면에서 기존 레코드가 새 CNAME(
myweb-xxx.pages.dev)으로 교체된다는 안내 확인 → Activate domain - 상태가
Initializing→ 몇 분 뒤Active(SSL 인증서 자동 발급)
6-3. www 주소도 함께 연결
www.ccumgol.net으로 접속하는 사람들을 위해 같은 과정을 한 번 더, 이번엔 www.ccumgol.net을 입력해서 추가합니다.
⚠️ apex(ccumgol.net)만 연결하면 www 주소는 522 오류가 납니다. www가 DNS상 apex의 별칭(CNAME)이어도, Pages는 “등록된 도메인”만 응답하기 때문입니다. (이슈 리포트 3번)
6-4. Hugo의 baseURL 설정
사이트 주소가 확정되면 config/_default/hugo.toml에서:
이후 커밋 & 푸시하면 RSS, 사이트맵, SNS 공유 링크가 올바른 절대 주소로 생성됩니다.
6-5. 최종 확인 체크리스트
7. 일상 운영: 글 쓰고 발행하기
이제 평소에는 이 순서만 반복하면 됩니다.
7-1. 새 글 작성
content/blog/ 폴더에 마크다운 파일을 만듭니다. 예: content/blog/my-new-post.md
7-2. 확인하고 발행
푸시 후 약 40초면 ccumgol.net에 반영됩니다. 반영 여부는 Cloudflare 대시보드의 Deployments 탭이나, 그냥 사이트 새로고침으로 확인하세요.
8. 비상 대응 (롤백)
사이트가 이상하게 배포됐을 때
Cloudflare → myweb → Deployments → 정상이었던 이전 배포의 ⋯ 메뉴 → Rollback to this deployment
기존 워드프레스로 도메인을 되돌려야 할 때
Cloudflare → ccumgol.net 도메인 → DNS에서 아래 값으로 복원:
| Type | Name | Content |
|——|——|———|
| A | @ | 88.223.84.188 |
| AAAA | @ | 2a02:4780:2b:1780:0:3371:efb5:8 |
| CNAME | www | ccumgol.net |
(그리고 Pages 프로젝트의 Custom domains에서 해당 도메인 제거)