Eric's Garden🌳

1. Obsidian 블로그 Quartz, 어떤 아키텍처가 좋을까?

12 min read

Obsidian을 사용하면서 Ghost를 셀프 호스팅해서 블로그를 관리하고 있었습니다. Ghost는 markdown 친화적이지 않고 글을 발행하기 불편하더군요. 아무래도 개인보다는 기업 친화적인 구성으로 느껴졌습니다. 그리고 셀프 호스팅이다 보니 서버를 가지고 놀다가 또는 통신사에서 문제가 생기면 블로그 접속도 단절돼서 포트폴리오 사용에도 문제가 생기고 여러모로 불편하더라고요. Obsidian을 활용해서 편하게 글을 발행하고 관리할 수 있는 방법이 없을까 하고 고민하던 찰나 Quartz 4를 알게 되었습니다.

1. Quartz 4?

Quartz 4는 Obsidian 노트를 웹사이트로 쉽게 발행하도록 도와주는 정적 사이트 생성기 (SSG Static Site Generator) 입니다. Quartz 4는 Obsidian 사용자들 사이에서 ‘디지털 가든’이나 ‘개인 블로그’를 구축하는 데 많이 활용되고 있습니다.

Obsidian Publish라는 Obsidian에서 자체 호스팅 서비스도 존재하지만 유료라는 단점이 있습니다.

저는 개인 서버를 이용해서 vault를 관리하고 Ghost도 시놀로지 DDNS를 사용해서 셀프 호스팅을 한 만큼 유료로 하고 싶진 않더라고요. 그래서 호스팅 서비스와 Quartz를 이용해보기로 했습니다.

2. Quartz 발행 아키텍처, 어떤 게 좋을까요?

Obsidian 발행을 위한 호스팅 플랫폼은 GitHub Pages와 Cloudflare Pages가 가장 대표적입니다. 두 서비스의 장단점을 간단히 비교해 봤어요.

항목🐙 GitHub Pages☁️ Cloudflare Pages
비용 (무료 플랜)무료무료
무료 호스트명[사용자명].github.io[프로젝트명].pages.dev
속도준수함 (CDN 제공)매우 빠름 (글로벌 CDN)
설정 편의성다소 복잡 (GitHub Actions .yml 수동 작성)매우 간편 (GUI 클릭 몇 번으로 완료)
Private 리포지토리❌ (Public 리포지토리만 무료)✅ (Private 리포지토리 무료 지원)

SSG인 Quartz에 크게 문제되지 않을 것 같고 제 누추한 블로그를 몇 분이나 보실까 싶어 다른 내용들은 크게 고려하지 않았습니다.

그렇다면 Quartz를 설정할 때 가장 먼저 고민하게 되는 부분이 ‘리포지토리 구조’예요. 쉽게 말해 “Quartz 소스코드와 내 글(.md 파일)을 한곳에 둘 거냐, 따로 둘 거냐” 하는 문제죠.

1) 1-Repo (Single Repository) 구조

이름 그대로, 하나의 GitHub 리포지토리 안에 Quartz 소스코드와 내 글(content 폴더)이 모두 들어있는 방식이에요.

  • 장점: 구조가 단순하고, Git Submodule 같은 복잡한 설정이 필요 없어서 처음 시작하기 쉬워요.
  • 단점: 만약 GitHub Pages 같은 무료 호스팅을 사용하려면 리포지토리가 Public(공개) 이어야 해요. 그럼 내 소중한 원본 .md 파일들(초안, 비공개 글 포함)이 인터넷에 전부 공개돼 버리죠.
2) 2-Repo (Dual Repository) 구조
  1. quartz-code : Quartz 소스코드만 담겨있어요. **Public(공개)**으로 둬도 상관없어요.
  2. quartz-content : 내 모든 .md 파일(Obsidian 볼트)만 담겨있어요. 이건 Private(비공개) 로 설정해서 철저하게 숨겨둡니다.

연결 방법은 quartz-code(공개) 리포지토리가 quartz-content(비공개) 리포지토리를 ‘Git Submodule’ 이라는 기능으로 참조(연결)하는 방식이에요.

  • 장점: 콘텐츠(내 글)를 비공개로 유지하면서 호스팅할 수 있어요.
  • 단점: 처음에 Git Submodule을 연결하고, Cloudflare가 Private 리포지토리에 접근할 수 있도록 인증 키(Deploy Key)를 설정하는 과정이 1-Repo 방식보다는 조금 더 복잡해요.

그렇다면 배포 방식을 선택해야 리포지토리 구조를 확정 지을 수 있을 것 같아 몇 가지 방법을 고민해봤어요.

2-1. 🐙 GitHub 활용 (DIY 방식)

  • 전략: GitHub Actions로 빌드하고, GitHub Pages로 호스팅하는 방식
  • 리포지토리 구조: 2-Repo (Public Code + Private Content)
    • 이유: GitHub Pages 무료 플랜은 Public 리포만 지원하므로, 콘텐츠 비공개를 위해 2-Repo가 강제됩니다.
  • 장점:
    • 강력한 커스터마이징, GitHub 생태계 내에서 모든 것 해결.
  • 단점:
    • Private 서브모듈 접근을 위한 별도 인증(PAT, Deploy Key) 설정이 매우 복잡함.
  • 결론: 설정이 너무 복잡해서 탈락.

2-2. ☁️ All-in-One 호스팅 (Cloudflare)

  • 전략: GitHub 리포지토리를 Cloudflare에 연결하여 빌드부터 배포까지 자동화하는 방식
  • 리포지토리 구조: 2-Repo (Public Code + Private Content)
  • 장점:
    • 압도적 편의성: Private 서브모듈 접근을 GUI 체크박스로 간단히 해결.
    • 간편한 자동화: code 리포지토리 Push 시, 알아서 빌드 및 CDN 배포.
  • 단점:
    • GitHub 외에 서드파티 서비스(Cloudflare)에 의존.
  • 결론: 편하긴 한데… 시놀로지 NAS를 활용하고 싶은데 이 방식은 NAS의 역할이 애매해져요. “굳이?” 라는 생각이 들어서 보류.

2-3. 🗄️ Synology 단독 활용 (Self-Hosting)

  • 전략: 외부 서비스 없이, 오직 시놀로지 NAS로만 빌드와 호스팅을 처리하는 방식
  • 리포지토리 구조: N/A (Git 불필요. NAS 내부 폴더만 사용)
  • 장점:
    • 완전한 셀프 호스팅.
  • 단점:
    • NAS가 꺼지면 블로그도 멈춤. (이건 Ghost 셀프 호스팅 시 겪었던 치명적 단점)
    • Watcher 방식은 초기 설정 난이도가 높음.
  • 결론: 안정성 문제로 탈락.

2-4. 🔄 Hybrid A (Synology + Public GitHub)

  • 전략: 시놀로지(Watcher/Cron)에서 자동 푸시하면, GitHub(Actions/Pages)가 받아 배포하는 방식
  • 리포지토리 구조: 1-Repo (Public)
  • 장점:
    • 높은 편의성: 글 저장만 하면 10분 뒤 자동 발행.
  • 단점 (치명적):
    • 콘텐츠 노출: Public 리포지토리만 무료이므로, 원본 .md 파일이 인터넷에 모두 공개됨.
  • 결론: 비공개 글까지 모두 공개되는 건 절대 안 되므로 탈락.

2-5. 🌟 Hybrid B (Synology + Private GitHub + Cloudflare)

  • 전략: 2-4의 단점(콘텐츠 노출)을 Cloudflare의 Private 리포지토리 지원 기능으로 해결한 방식
  • 리포지토리 구조: 1-Repo (Private)
    • 이유: Cloudflare가 Private 리포지토리를 무료로 지원하므로, 2-Repo처럼 복잡하게 구성할 필요 없이 1-Repo로 단순하게 관리 가능!
  • 워크플로우:
    1. Synology (Cron): 10분마다 글 변경 감지.
    2. Synology (Auto Push): git push를 Private GitHub 리포지토리로 자동 전송.
    3. Cloudflare (Pages): Push 감지 후, Private 리포에서 자동 빌드.
    4. Cloudflare (CDN): 빌드 결과물을 [프로젝트명].pages.dev에 배포.
  • 장점:
    • 완전 비공개: Private 1-Repo를 Cloudflare가 무료로 지원.
    • 완전 무료: 모든 구성요소(Private Repo, CI/CD, Hosting) 무료.
    • 완전 자동화: 글쓰기에만 집중 가능.
    • 간편한 빌드: .yml 파일 불필요, Cloudflare GUI로 설정.
    • 최고 속도 & 안정성: Cloudflare CDN으로 호스팅 (NAS가 꺼져도 블로그는 유지됨).
  • 단점:
    • 초기 NAS-GitHub 인증 설정이 필요함.
  • 결론: 최종 선택! 🤩 (비공개, 자동화, 무료, NAS 활용, 안정성 모두 만족)

3. Watcher? Cron?

배포 방식(Hybrid B)은 정했는데, 이제 시놀로지에서 GitHub로 푸시하는 트리거를 정해야 했어요.

파일 변경을 감지하는 방식으로 Watcher (이벤트 기반)와 Cron (스케줄링)을 알아봤는데,

Watcher 방식(예: inotify-tools)은 파일이 변경되는 즉시 이벤트를 감지해 자동화를 실행시켜 Vercel이나 Cloudflare와 거의 동일한 경험을 줘요. 하지만 시놀로지 NAS에 별도 패키지를 설치하고 스크립트를 항상 실행(상주)시켜야 해서 초기 설정이 꽤 복잡하고 관리가 까다로울 수 있어요.

반면에 Cron 방식은 시놀로지 NAS에 내장된 ‘작업 스케줄러’ 기능을 이용하는 거예요. ‘매 10분마다 스크립트 실행’처럼 간단히 설정할 수 있죠.

개인 블로그는 글을 저장하자마자 1초 만에 배포될 필요는 없다고 생각해요. 10분 정도의 간격을 두고 주기적으로 변경 사항을 체크(git push)해도 충분하죠.

이 Cron 방식이

  1. 설정이 압도적으로 간편하고,
  2. NAS에 추가 부담을 주지 않으며,
  3. 안정적으로 작동해요.

그래서 저는 복잡한 Watcher 대신, 시놀로지 ‘작업 스케줄러(Cron)’ 를 이용해 10분마다 자동 푸시하는 방식을 최종적으로 선택했어요.

요약

  1. 호스팅: Cloudflare Pages (Private 리포지토리 무료 지원, 빠른 CDN)
  2. 리포지토리: 1-Repo (Private) (관리가 단순하고 콘텐츠 비공개)
  3. 배포 트리거: Synology Cron (시놀로지 작업 스케줄러로 10분마다 git push)
  4. 최종 아키텍처: Synology (Cron) + Private 1-Repo (GitHub) + Cloudflare Pages

최신글

그래프 뷰