Hugo + BlowFish로 블로그 만들면서 겪은 온갖 삽질들#
블로그를 만든다는 게 이렇게 험난할 줄 몰랐어요… 😅
공식 문서대로 차근차근 따라했는데 **“어? 왜 안 되지?”**라고 중얼거린 게 몇 번인지 모르겠네요. 그래서 이번엔 제가 실제로 겪은 모든 삽질들과 해결 과정을 솔직하게 기록해봤습니다.
혹시 저와 같은 함정에 빠지실 분들을 위해서요! 🕳️
1. 첫 번째 관문: Hugo 설치부터 삽질#
😤 Chocolatey 권한 오류의 지옥#
처음엔 당연히 Chocolatey로 설치하려 했죠. 그런데 이게 웬걸?
'C:\ProgramData\chocolatey\.chocolatey' 경로에 대한 액세스가 거부되었습니다.
Unable to obtain lock file access
“아, 관리자 권한이겠구나” 싶어서 관리자로 실행해도 똑같은 오류. 구글링을 해보니 락 파일 충돌이라는데… 이게 뭔 소리인지 😵💫
결국 찾은 해결책:
# 문제의 락 파일 강제 삭제
Remove-Item "C:\ProgramData\chocolatey\lib\ce020f33af5688ae4fa36aaf09180accb9de9921" -Force
choco install hugo-extended -y
하지만 더 좋은 방법을 발견했어요:
# Winget 최고! 권한 문제 전혀 없음
winget install Hugo.Hugo.Extended
교훈: Windows에서는 그냥 Winget 쓰세요. Chocolatey는 괜한 고생만…
🤦♂️ “Hugo 명령어를 찾을 수 없습니다”#
Hugo 설치는 완료! 그런데 터미널에서 hugo version을 쳐도…
hugo : 'hugo' 용어가 cmdlet, 함수, 스크립트 파일 또는 실행할 수 있는 프로그램 이름으로 인식되지 않습니다.
“분명 설치했는데 왜?!”
PATH 환경변수가 업데이트되었는데 현재 세션에 반영이 안 된 거더라고요. IntelliJ를 완전히 재시작하니까 바로 해결되었어요.
간단한 거였는데 왜 이렇게 당황했을까요… 🤷♂️
2. Git 연동하다가 또 삽질#
😡 GitHub 인증 실패의 늪#
기존에 쓰던 방식대로 HTTPS URL로 clone했는데:
remote: Invalid username or token. Password authentication is not supported for Git operations.
fatal: Authentication failed
“어? 비밀번호가 틀렸나?” 싶어서 몇 번 다시 입력해봤는데 계속 실패. 알고 보니 GitHub에서 2021년부터 비밀번호 인증을 막아버렸더라고요.
두 가지 해결 방법이 있었어요:
방법 1: Personal Access Token 귀찮지만 token 만들어서 비밀번호 대신 사용
방법 2: SSH 키 (강력 추천!)
# 한 번만 설정하면 끝
ssh-keygen -t ed25519 -C "[email protected]"
cat ~/.ssh/id_ed25519.pub # GitHub에 등록
# URL 변경
git remote set-url origin [email protected]:username/repo.git
SSH 키 방식이 훨씬 편해요. 토큰은 만료되면 또 바꿔야 하거든요.
🤪 .gitignore가 무시당하는 기막힌 상황#
public/ 폴더를 .gitignore에 추가했는데 계속 스테이징에 잡히더라고요.
“분명히 .gitignore에 넣었는데 왜?!”
알고 보니 이미 Git 추적 중인 파일들은 .gitignore를 무시한다는 사실! 이런 기본적인 것도 모르고 있었다니… 😅
# 추적 중인 파일을 Git에서 제거 (실제 파일은 그대로)
git rm -r --cached public/
git rm -r --cached .idea/
git commit -m "Remove tracked files that should be ignored"
이제야 .gitignore가 제대로 작동했어요.
3. 배포하다가 만난 최대 위기#
😱 502 Bad Gateway의 공포#
로컬에서는 잘 되는데 실제 도메인으로 접속하면 502 Bad Gateway만 뜨는 거예요.
“뭐가 문제지?!” 하면서 몇 시간 동안 헤맸는데…
진범은 DNS 설정이었어요:
# 현재 내 서버 IP 확인
curl ifconfig.me
# → 123.456.789.012
# 도메인이 가리키는 IP 확인
nslookup coderred.com
# → 111.222.333.444 (다른 IP!)
Cloudflare에서 **주황색 구름(프록시 모드)**을 **회색 구름(DNS 모드)**로 바꾸고, A 레코드를 실제 서버 IP로 수정하니까 해결되었어요.
이런 기본적인 걸 놓치다니… 정말 허무했어요. 🤦♂️
🐳 Docker 컨테이너들이 서로 못 찾는 문제#
Nginx Proxy Manager와 Hugo 컨테이너를 연결하려는데 자꾸 502 에러가…
원인: 서로 다른 Docker 네트워크에 있어서 통신이 안 되는 거였어요.
해결 방법들:
- 물리 IP 사용 (가장 간단)
- 같은 네트워크에 배치
- 컨테이너 이름으로 접근
저는 그냥 물리 IP 써서 해결했어요. 복잡하게 생각할 필요 없더라고요.
4. BlowFish 테마 커스터마이징 함정들#
🤯 사이트 제목이 바뀌지 않는 미스터리#
config.toml에서 title = "내 블로그"로 바꿨는데 계속 “BlowFish"만 뜨는 거예요.
“설정 파일이 잘못됐나?” 하면서 몇십 번 수정해봤는데 변화 없음…
알고 보니 진짜 제목은 languages.ko.toml에서 설정해야 하는 거였어요!
# config/_default/languages.ko.toml (여기가 진짜!)
title = "CoderRed의 개발 블로그"
# config/_default/config.toml (여긴 효과 없음)
title = "내 블로그" # 이걸로는 안 바뀜
이런 함정이… 공식 문서에도 명확하게 안 나와 있어서 정말 헤맸어요. 😤
🔄 캐시 때문에 변경사항이 안 보이는 상황#
설정을 바꿨는데 브라우저에서 여전히 옛날 모습이 보이더라고요.
범인들:
- 브라우저 캐시: Ctrl + F5로 강제 새로고침
- Cloudflare 캐시: Purge Everything 클릭
- Hugo 캐시:
hugo mod clean --all
캐시 문제는 정말 개발자의 영원한 숙적인 것 같아요… 😅
5. 개발 환경 구축하면서 겪은 소소한 삽질들#
💻 IntelliJ에서 Hugo가 인식 안 됨#
Hugo 프로젝트를 열었는데 그냥 일반 폴더로만 인식되더라고요.
해결책:
- Hugo Integration 플러그인 설치
- 프로젝트를 Hugo 루트 폴더로 열기
- 터미널에서
hugo version정상 작동 확인
플러그인 하나면 해결되는 일이었는데 왜 이걸 몰랐을까요…
🔍 로컬과 실서버가 다르게 보이는 문제#
로컬에서는 멀쩡한데 실서버에 올리면 레이아웃이 깨지는 황당한 상황.
원인: 빌드 환경 차이
해결책:
# 로컬 개발용
hugo server -D --bind=0.0.0.0
# 실서버와 동일한 프로덕션 빌드로 테스트
hugo --minify --cleanDestinationDir
로컬에서도 프로덕션 빌드로 미리 확인해보는 습관을 들여야겠어요.
6. 자주 하는 실수들과 예방책#
제가 실제로 저지른 바보 같은 실수들이에요… 😅
실수 1: public 폴더를 Git에 올림#
# 반드시 .gitignore에 추가!
public/
resources/_gen/
.hugo_build.lock
.idea/
실수 2: 포스트 구조를 잘못 만듦#
# 잘못된 구조
content/posts/post-name.md
# 올바른 구조 (이미지 등 첨부 가능)
content/posts/post-name/
├── index.md
└── images/
실수 3: Front Matter 문법 오류#
# YAML 문법 주의! 콜론 뒤에 공백 필수
---
title: "포스트 제목" # ✅
date:2024-09-04 # ❌ 공백 없음
tags: ["tag1", "tag2"] # ✅
---
작은 실수 하나가 전체를 망가뜨리더라고요.
7. 삽질하면서 만든 나만의 디버깅 체크리스트#
문제 생기면 이 순서대로 확인해요:
📋 로컬 환경 체크#
-
hugo version(0.141.0 이상인가?) -
hugo server -D정상 작동하나? - Git 상태는 깨끗한가?
🌐 네트워크 체크#
- 공인 IP:
curl ifconfig.me - DNS:
nslookup domain.com - 포트:
netstat -tlnp | grep :80
🐳 서버 환경 체크#
- Docker:
docker ps - 로그:
docker logs container-name - Nginx 설정 확인
🗂️ 캐시 체크#
- 브라우저 캐시 (Ctrl + F5)
- Cloudflare 캐시 (Purge All)
- DNS 캐시 (
ipconfig /flushdns)
이 체크리스트 덕분에 이제 삽질 시간이 많이 줄었어요!
8. 자주 쓰는 명령어들 (나중에 까먹을 나를 위해)#
# Hugo 관련 (매일 씀)
hugo new posts/post-name/index.md # 새 글 작성
hugo server -D # 로컬 미리보기
hugo --minify # 배포용 빌드
# Docker 관리 (가끔 씀)
docker ps # 뭐가 돌고 있나?
docker logs hugo-blog # 로그 확인
docker restart hugo-blog # 재시작
# Git 워크플로우 (매일 씀)
git add . # 모든 변경사항
git commit -m "글 추가" # 커밋
git push origin main # 업로드
# 네트워크 디버깅 (삽질할 때만)
curl ifconfig.me # 내 IP가 뭐지?
nslookup domain.com # DNS 확인
curl -I https://domain.com # 응답 헤더 보기
마무리하며: 삽질도 성장이다#
이렇게 정리하고 보니 정말 많은 삽질을 했네요… 😅
하지만 덕분에 Hugo와 BlowFish에 대해 정말 많이 알게 되었어요. 공식 문서만으로는 절대 알 수 없는 실전 노하우들을 얻었거든요.
삽질하면서 깨달은 것들:
- 공식 문서가 항상 완벽하지 않다
- 캐시는 개발자의 영원한 적이다
- 간단한 것부터 확인하는 습관이 중요하다
- SSH 키가 HTTPS보다 편하다
- 네트워크 문제는 대부분 DNS다
혹시 저와 같은 삽질을 하고 계신 분들이 있다면, 이 글이 조금이라도 도움이 되길 바라요.
우리 모두 삽질을 통해 성장하는 개발자가 되어봅시다! 🚀
(그래도 삽질은 최대한 줄이고 싶긴 하지만요… 😂)