jaysnote는 어떤 기술로 만들었나 — 스택과 흐름 쉽게 풀기

이 사이트(jaysnote.com)는 어떤 기술로 만들어졌고, 글 한 편이 어떻게 올라가고 어떻게 보여지는지를 쉽게 풀어 본다. 용어를 모르는 사람도 따라올 수 있게 쓰고, 무엇보다 왜 이런 기술들을 골랐는지를 자세히 적는다.

한 줄 철학

서버 없이, 글은 파일로, 인증은 남이 만든 튼튼한 걸로.

이 한 줄이 모든 선택의 기준이다. 직접 운영하는 서버가 없으면 해킹당할 표면이 거의 없고, 글을 파일(마크다운)로 두면 버전 관리와 자동화가 쉬우며, 로그인 같은 위험한 코드는 직접 만들지 않고 검증된 서비스에 맡긴다.

전체 그림

큰 흐름은 이렇다: 글(마크다운) → GitHub → 자동 빌드 → Cloudflare로 배포 → 방문자에게 전달. 이제 각 조각이 무엇이고 왜 골랐는지 하나씩 본다.

각 기술, 쉽게 + 왜 골랐나

1. 마크다운 + Git — “글을 파일로 관리한다”

• 쉽게: 글을 데이터베이스가 아니라 텍스트 파일(.md) 로 저장한다. 제목·날짜·태그는 파일 맨 위 몇 줄(frontmatter)에 적는다. Git은 그 파일들의 변경 이력을 통째로 기록하는 도구다.
• 왜: 글이 파일이면 누가 언제 무엇을 바꿨는지 다 남고, 되돌리기 쉽고, 사람도 AI(OpenClaw/ Claude)도 똑같이 파일만 쓰면 게시가 된다. 데이터베이스를 운영할 필요가 없다.

2. Astro — “파일을 웹페이지로 굽는 도구”

• 쉽게: 마크다운 글들을 받아서 완성된 HTML 페이지로 만들어 주는 정적 사이트 생성기다. 방문자가 올 때 계산하는 게 아니라, 미리 다 만들어 둔 페이지를 보여준다.
• 왜 Astro인가 (WordPress·Next.js 대신):
  • 빠르다. 자바스크립트를 거의 안 실어서 가볍다(특히 모바일에서 체감).
  • 콘텐츠 중심. 마크다운·태그·시리즈 같은 글 중심 기능과 잘 맞고, 글의 형식을 코드로 검증(type-safe)해 잘못된 글은 아예 배포가 안 된다.
  • 기본기를 챙겨 준다. 이미지 자동 최적화(WebP 변환), 폰트 최적화, 부드러운 페이지 전환, 검색 친화적 HTML이 다 들어 있다.
  • 서버가 필요 없다. 결과물이 그냥 파일이라 아무 데나 올리면 끝 → 보안·비용에 유리.

3. GitHub(비공개 저장소) + GitHub Actions — “보관소 + 자동 일꾼”

• 쉽게: GitHub는 그 파일들을 보관하는 비공개 창고다. GitHub Actions는 창고에 새 글이 들어오면 자동으로 정해진 일을 수행하는 로봇 일꾼이다.
• 왜: 개인 저장소라 글 원본은 비공개로 안전하고, 글을 올리면(push) 자동으로 빌드·배포가 돌아간다(사람이 매번 손댈 필요 없음). 개인 용도엔 무료 한도로 충분하다.

4. Pagefind — “서버 없는 검색”

• 쉽게: 보통 검색은 검색 서버가 필요한데, Pagefind는 빌드할 때 검색용 색인(index)을 미리 만들어 두고, 방문자의 브라우저에서 그 색인으로 찾는다. 즉 서버 없이 전문 검색이 된다.
• 왜: 정적 사이트 철학과 딱 맞고, 무엇보다 공개용·비공개용 색인을 따로 만들 수 있다. 덕분에 공개 검색에는 비공개 글이 단 한 글자도 새지 않는다(아래 인증 흐름 참고).

5. Cloudflare Pages — “전 세계에 뿌려 주는 무료 배달망”

• 쉽게: 완성된 페이지 파일들을 전 세계 서버(CDN)에 올려 방문자에게 가까운 곳에서 빠르게 전달한다.
• 왜: 무료 + 대역폭 무제한, 도메인 연결이 쉽고, 빠르다. 서버를 직접 굴리지 않으니 운영 부담이 없다.

6. Cloudflare Access(Google 로그인) — “남이 만든 튼튼한 자물쇠”

• 쉽게: 비공개 글(/private/...)에 누가 접근하면, Cloudflare가 입구에서 먼저 막고 Google 로그인을 시킨다. 통과한 사람에게만 페이지를 내준다.
• 왜: 로그인·세션 같은 코드는 직접 만들면 그게 곧 해킹 표면이다. Access는 그 일을 요청이 사이트에 닿기도 전에(엣지에서) 대신 처리해 준다. 자체 인증 코드가 0줄이라 그쪽으로 뚫릴 일이 없다. 게다가 무료다.

게시 흐름 — 글 한 편이 올라가기까지

1. 글을 쓴다. 내가 직접 쓰거나, OpenClaw/Claude에게 “이거 정리해서 올려줘” 라고 시킨다.
2. 게시 스크립트가 형식을 맞춘다. 제목·태그·정확한 날짜(시각까지)·분류를 넣어 마크다운 파일을 만든다. (날짜를 사람이 추측하지 않고 시스템 시간으로 채워서 항상 최신순 정렬이 맞는다.)
3. git push. 그 파일이 GitHub 비공개 저장소로 올라간다.
4. GitHub Actions가 자동으로 일한다:
   • npm ci — 필요한 도구 설치
   • astro build — 마크다운을 HTML 페이지로 굽기
   • pagefind — 검색 색인 생성(공개용·비공개용 분리)
   • wrangler deploy — 결과물을 Cloudflare Pages로 업로드(바뀐 파일만 올림)
5. Cloudflare Pages가 배포한다. 전 세계 CDN에 반영.
6. 1~2분 안에 jaysnote.com에 게시 완료.

핵심은 “글을 push하는 순간 나머지는 전부 자동” 이라는 점이다. 빌드가 깨지면 배포가 안 되므로, 형식이 틀린 글이 사이트에 새어 나가지도 않는다.

방문 & 인증 흐름 — 누가 무엇을 보나

방문자가 페이지를 요청하면 두 갈래로 나뉜다.

• 공개 글(/posts/...) → Cloudflare CDN이 누구에게나 빠르게 캐시된 페이지를 내준다.
• 비공개 글(/private/...) → Cloudflare Access가 입구에서 가로챈다. 로그인 안 한 사람은 Google 로그인 화면으로 보내고, 내 계정으로 통과한 사람에게만 페이지를 내준다. 인증이 없으면 정적 파일 자체가 전송되지 않는다(엣지에서 차단).

검색도 새지 않게 둘로 나눴다

검색 색인을 공개용 / 비공개용 두 개로 만든다.

• 공개 검색은 공개 색인만 본다 → 비공개 글은 검색 결과에도, 미리보기 스니펫에도 안 나온다.
• 비공개 색인은 /private/ 안에 있어 Access 뒤에 숨는다 → 인증해야만 검색까지 된다.

즉 “공개 검색에 비공개가 새지 않는다”가 우연이 아니라 구조적으로 보장된다.

왜 이 조합인가 — 종합

기준	이 스택이 주는 답
보안	운영 서버·자체 로그인 코드가 없음 → 공격 표면 최소. 인증은 Cloudflare Access(엣지)에 위임
속도	미리 구운 정적 페이지 + 전 세계 CDN + 가벼운 JS → 특히 모바일에서 빠름
비용	호스팅·검색·인증·CI가 무료 범위. 실지출은 도메인값과 글 쓸 때 쓰는 AI 토큰 정도
자동화	글은 파일 → push 한 번이면 빌드·검색색인·배포가 전부 자동. AI에게 위임도 자연스러움
단순함	데이터베이스·서버·검색엔진을 따로 운영하지 않음 → 관리할 게 적음

하나하나는 평범한 선택이지만, “정적 파일 + 엣지 인증” 이라는 한 가지 원칙으로 꿰어서 고르면 보안·속도·비용·자동화가 동시에 좋아진다. 그게 이 스택을 고른 이유다.

더 깊은 설계 문서(PRD·아키텍처·스펙)는 저장소 docs/에 정리돼 있다.