본문으로 건너뛰기

Hugo 블로그 구축기 1편 - 환경 설정부터 배포까지

·1113 단어수·6 분
Hugo 블로그 구축기 - 이 글은 시리즈의 일부입니다.
부분 : 이 글

Hugo BlowFish로 나만의 블로그 만들기
#

정적 사이트 생성기로 블로그를 만들어보고 싶다는 생각, 한 번쯤은 해보셨죠? 저도 그랬어요! WordPress는 너무 무겁고, Jekyll은 뭔가 복잡하고… 그러다 Hugo를 알게 되었고, 특히 BlowFish 테마가 정말 마음에 들더라고요. 🎯

이번 글에서는 제가 실제로 이 블로그를 만들면서 겪은 모든 시행착오해결 과정을 공유해드릴게요. Windows에서 IntelliJ로 개발하고, Linux 서버에 Docker로 배포하는 전 과정을 담았습니다.

왜 Hugo + BlowFish를 선택했을까?
#

블로그 플랫폼을 고민하다가 Hugo를 선택한 이유:

  • 빠른 빌드 속도 - 몇 초만에 사이트 전체 생성
  • Markdown 기반 - 개발자에게 익숙한 문법
  • 정적 파일 - 서버 부담 없이 빠른 로딩
  • 무료 호스팅 - GitHub Pages, Netlify 등 다양한 옵션

그 중에서도 BlowFish 테마는:

  • 깔끔한 디자인 - Tailwind CSS 기반의 모던한 UI
  • 다크모드 지원 - 개발자 친화적 😎
  • 풍부한 기능 - 태그, 시리즈, 검색 등 블로그에 필요한 모든 기능
  • 활발한 업데이트 - 지속적인 개선과 버그 수정

1. Hugo 설치하기 - Windows 환경
#

처음엔 Chocolatey로 설치하려다가 권한 문제로 고생했어요. 결국 Winget으로 해결했습니다!

추천 방법: Winget 사용
#

# Windows 10/11에서 기본 제공되는 패키지 매니저
winget install Hugo.Hugo.Extended

대안 방법들
#

# Chocolatey 사용 (관리자 권한 필요)
choco install hugo-extended

# 직접 다운로드
# https://github.com/gohugoio/hugo/releases에서 
# hugo_extended_x.x.x_windows-amd64.zip 다운로드

꿀팁: Hugo 명령어가 인식되지 않으면 IntelliJ를 재시작해보세요. PATH 설정이 바로 적용되지 않을 수 있어요.

2. 새 블로그 프로젝트 생성
#

# 블로그 프로젝트 폴더 생성
hugo new site my-awesome-blog
cd my-awesome-blog

# Git 저장소 초기화 (테마 설치에 필요)
git init

IntelliJ에서 이 폴더를 열면 Hugo 프로젝트 구조를 한눈에 볼 수 있어요. 저는 개발할 때 IntelliJ의 터미널을 주로 사용했어요.

3. BlowFish 테마 설치 - 이게 핵심!
#

여기서부터가 진짜 시작이에요. 공식 문서대로 따라해도 안 되는 부분들이 있더라고요.

3-1. 테마 다운로드
#

# Git submodule로 테마 추가 (추천 방식)
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

3-2. 설정 파일 복사 (중요!)
#

# config 폴더 구조 생성
mkdir -p config/_default/languages

# 테마의 기본 설정 파일들을 프로젝트로 복사
cp themes/blowfish/config/_default/* config/_default/
cp themes/blowfish/config/_default/languages/ko.toml config/_default/languages/

여기서 실수하기 쉬운 부분: 설정 파일을 복사하지 않고 바로 시작하면 기본 Hugo 테마처럼 밋밋하게 나와요. 꼭 복사해주세요!

4. 핵심 설정하기
#

4-1. 기본 사이트 설정
#

config/_default/config.toml 파일을 열어서:

baseURL = "https://yourdomain.com"  # 실제 도메인으로 변경
languageCode = "ko" 
title = "내 블로그"  # 임시 제목 (실제로는 languages.ko.toml에서 설정)
theme = "blowfish"

# Google Analytics (나중에 설정)
[services]
  [services.googleAnalytics]
    id = "G-XXXXXXXXXX"

4-2. 한국어 설정 (가장 중요!)
#

여기서 큰 함정이 있어요! config.toml의 title은 실제로 표시되지 않습니다. 진짜 제목은 languages.ko.toml에서 설정해야 해요.

# 한국어 설정 파일 생성
cp config/_default/languages.en.toml config/_default/languages.ko.toml
cp config/_default/menus.en.toml config/_default/menus.ko.toml

config/_default/languages.ko.toml:

languageCode = "ko"
languageName = "한국어"
displayName = "KO"
isoCode = "ko"
weight = 1
rtl = false

title = "CoderRed의 개발 블로그"  # 실제 헤더에 표시되는 제목!
dateFormat = "2006년 1월 2일"

[author]
  name = "CoderRed"
  image = "images/author.jpg"
  headline = "개발자의 기록과 성장 이야기"
  bio = "백엔드 개발자이자 기술 탐험가입니다. 배우고 경험한 것들을 기록하며 공유합니다."
  links = [
    { email = "mailto:[email protected]" },
    { github = "https://github.com/yourusername" },
    { twitter = "https://twitter.com/yourusername" }
  ]

4-3. 메뉴 설정
#

config/_default/menus.ko.toml:

# 상단 네비게이션
[[main]]
  name = "홈"
  pageRef = "/"
  weight = 10

[[main]]
  name = "포스트"
  pageRef = "/posts"
  weight = 20

[[main]]
  name = "태그"
  pageRef = "/tags"
  weight = 30

[[main]]
  name = "시리즈"
  pageRef = "/series"
  weight = 35

[[main]]
  name = "소개"
  pageRef = "/about"
  weight = 40

# 하단 푸터 메뉴
[[footer]]
  name = "개인정보처리방침"
  pageRef = "/privacy"
  weight = 10

[[footer]]
  name = "연락처"
  pageRef = "/contact"
  weight = 20

5. 첫 번째 포스트 작성해보기
#

드디어 글을 써볼 시간이에요!

# 새 포스트 생성 (Bundle 형태로)
hugo new posts/my-first-post/index.md

생성된 content/posts/my-first-post/index.md 파일:

---
title: "Hugo BlowFish로 블로그 시작하기"
date: 2025-09-04T17:30:00+09:00
draft: false
author: "CoderRed"
description: "Hugo와 BlowFish 테마로 만든 첫 번째 포스트입니다."
tags: ["Hugo", "BlowFish", "블로그", "시작"]
categories: ["블로그"]
series: ["블로그 시작하기"]
showToc: true
---

# 안녕하세요! 👋

Hugo와 BlowFish 테마로 만든 첫 번째 포스트입니다.

## 왜 Hugo를 선택했나요?

정적 사이트 생성기 중에서 Hugo를 선택한 이유는...

- **빠른 속도** ⚡
- **간편한 설정** ⚙️  
- **풍부한 테마** 🎨
- **Markdown 지원** 📝

## 앞으로의 계획

앞으로 이 블로그에서는 다음과 같은 내용들을 다룰 예정입니다:

1. 개발 경험담
2. 기술 학습 노트
3. 프로젝트 회고
4. 일상 이야기

함께 성장해나가요! 🚀

6. 로컬에서 확인해보기
#

# 개발 서버 시작 (드래프트 포함)
hugo server -D

# 브라우저에서 http://localhost:1313 접속

짜잔! 🎉 블로그가 나타났나요? 처음 보는 순간의 그 감동이란…

7. 자주 만나는 문제들과 해결법
#

실제로 설정하면서 만났던 문제들이에요:

7-1. Hugo 버전 호환성 문제
#

Error: BlowFish theme requires Hugo version 0.141.0 or higher

해결법: 최신 Extended 버전으로 업데이트

winget upgrade Hugo.Hugo.Extended

7-2. “paginate deprecated” 경고
#

# config/_default/config.toml에서
# 기존: paginate = 10
# 변경:
[pagination]
  pagerSize = 10

7-3. 템플릿 함수 오류
#

Error: template function "try" not defined

해결법:

# Hugo 캐시 정리
hugo mod clean --all

# 서버 재시작
hugo server -D --disableFastRender

8. GitHub에 올리기
#

로컬에서 잘 돌아간다면 이제 GitHub에 올려봅시다!

8-1. .gitignore 설정
#

# Hugo 관련
public/
resources/_gen/
.hugo_build.lock

# IDE 관련
.idea/
.vscode/

# 기타
.DS_Store
Thumbs.db

8-2. GitHub 저장소 생성 및 푸시
#

# 파일 추가
git add .
git commit -m "Initial commit: Hugo BlowFish 블로그 설정"

# GitHub 저장소 연결 (SSH 권장)
git remote add origin [email protected]:yourusername/your-blog.git
git branch -M main
git push -u origin main

GitHub SSH 키 설정 팁: 처음에 HTTPS로 했다가 토큰 인증 문제로 고생했어요. SSH 키 설정하는 게 훨씬 편해요!

9. 서버 배포하기 (Docker 사용)
#

로컬에서만 보기엔 아쉽죠? 이제 실제 서버에 배포해봅시다!

9-1. Hugo 빌드
#

# 프로덕션용 빌드
hugo --minify --cleanDestinationDir

9-2. Docker로 배포
#

# Nginx 컨테이너로 실행
docker run -d \
  --name hugo-blog \
  --restart unless-stopped \
  -p 9572:80 \
  -v ~/coderblog/public:/usr/share/nginx/html:ro \
  nginx:alpine

9-3. 자동 배포 스크립트
#

매번 수동으로 배포하기 귀찮으니까 스크립트를 만들어봤어요:

#!/bin/bash
# deploy.sh
echo "🚀 블로그 배포 시작..."

cd ~/coderblog
git pull origin main

echo "📦 Hugo 빌드 중..."
hugo --minify --cleanDestinationDir

echo "🐳 Docker 컨테이너 재시작..."
docker stop hugo-blog 2>/dev/null || true
docker rm hugo-blog 2>/dev/null || true

docker run -d \
  --name hugo-blog \
  --restart unless-stopped \
  -p 9572:80 \
  -v ~/coderblog/public:/usr/share/nginx/html:ro \
  nginx:alpine

echo "✅ 배포 완료! https://coderred.com"

10. 유용한 Hugo 명령어들
#

개발하면서 자주 사용하는 명령어들이에요:

# 새 포스트 생성 (Bundle 형태)
hugo new posts/post-name/index.md

# 새 페이지 생성
hugo new about/index.md

# 드래프트 포함해서 서버 실행
hugo server -D

# 미래 날짜 포스트도 포함해서 빌드
hugo -F

# 특정 환경으로 빌드
hugo --environment production

# 사이트 통계 확인
hugo list all

마무리하며
#

드디어 나만의 블로그가 완성되었네요! 🎉

처음엔 복잡해 보였지만, 차근차근 따라하다 보면 생각보다 어렵지 않아요. 특히 BlowFish 테마는 정말 잘 만들어진 것 같아요. 기능도 풍부하고 디자인도 깔끔하고!

앞으로의 계획:

  • GitHub Actions로 자동 배포 설정
  • Google Analytics 연동
  • 댓글 시스템 추가 (Giscus)
  • 검색 기능 활성화
  • SEO 최적화

블로그를 시작하는 것은 첫 발걸음일 뿐이에요. 이제 꾸준히 좋은 글들을 써나가는 게 진짜 시작이죠! 함께 성장해나가요! 🚀

Hugo 블로그 구축기 - 이 글은 시리즈의 일부입니다.
부분 : 이 글