ghost.sori.studio/docs/deploy.md

배포 가이드

현재 버전

• v0.1.40

Git 기본 설정

• 저장소 작성자 정보는 아래 값으로 통일한다.
• 이름: zenn
• 이메일: zenn.message@gmail.com

git config user.name "zenn"
git config user.email "zenn.message@gmail.com"

저장소 초기화

git init
git branch -M main
git remote add origin https://git.sori.studio/zenn/sori.studio.git

작업 종료 시 업로드 절차

1. 변경 파일과 문서 반영 상태를 확인한다.
2. 작성자 정보가 올바른지 확인한다.
3. 모든 변경을 스테이징한다.
4. 한국어 커밋 메시지로 커밋한다.
5. main 브랜치로 원격 저장소에 푸시한다.
6. 마지막 커밋과 작업 트리가 정상인지 다시 확인한다.

git config user.name
git config user.email
git status
git add -A
git commit -m "영역: 작업 내용"
git push origin main
git status
git log -1 --oneline

로컬 실행

npm install
npm run dev

로컬 실시간 확인

npm run dev:ghost:start
npm run dev:watch

• npm run dev:ghost:start는 로컬 Ghost 컨테이너를 시작한다.
• npm run dev:watch는 초기 빌드와 sync를 한 번 수행한 뒤, Tailwind watch와 파일 변경 감지 기반 theme sync를 계속 유지한다.
• 템플릿이나 자산을 저장한 뒤 브라우저 새로고침만으로 바로 반영 상태를 확인할 수 있다.

로컬 스타일 빌드

npm run build:alpine
npm run build:tailwind

• npm run dev, npm run dev:ghost:start, npm run dev:ghost:restart 실행 시 Alpine.js와 Tailwind 빌드가 먼저 수행된다.
• Alpine 결과물은 assets/built/alpine.js에 생성된다.
• Tailwind 결과물은 assets/built/tailwind.css에 생성되고, Ghost 테마에서 screen.css 다음에 로드된다.

업로드용 zip 생성

npm run zip:version

• 현재 package.json 버전을 기준으로 thred-inspired-theme-v0.x.x.zip 파일을 생성한다.

/tags/, /authors/ 연결 방법

• 가장 쉬운 방법은 Ghost Admin에서 페이지를 만들고 슬러그를 각각 tags, authors로 지정한 뒤 템플릿을 연결하는 방식이다.
• 페이지 방식 대신 커스텀 라우트를 쓰려면 routes.yaml.example를 기준으로 Ghost의 routes.yaml에 /tags/, /authors/를 연결한다.

로컬 빌드 검증

npm run build

저장 기능 메모

• DB 연결 환경에서는 작성/수정 API가 Prisma를 통해 실제 데이터를 저장한다.
• DB 미연결 환경에서는 샘플 콘텐츠 fallback이 프로세스 메모리에서만 갱신된다.
• 따라서 재시작 이후에도 데이터를 유지하려면 PostgreSQL 연결이 필요하다.

폰트 에셋

• Pretendard 폰트 파일은 assets/fonts 경로를 사용한다.
• 전역 CSS 로딩에 assets/fonts/pretendard.css가 포함되어 있어야 한다.

PostgreSQL 준비

cp .env.example .env
npm run db:push
npm run db:seed-admin

데모 로그인 계정

• 이메일: zenn.message@gmail.com
• 비밀번호: zenn-demo-admin
• 실제 운영 전에는 .env에서 데모 인증 값을 반드시 변경한다.

관리자 계정 시드

• DB 연결 환경에서는 npm run db:seed-admin으로 초기 관리자 계정을 생성하거나 갱신한다.
• 시드 계정 정보는 .env의 DEMO_ADMIN_* 값을 사용한다.
• 실제 운영 전에는 기본 비밀번호를 반드시 변경한다.

원격 저장소 정보

• 기본 원격 이름: origin
• 기본 저장소 주소: https://git.sori.studio/zenn/sori.studio.git

운영 메모

• 민감 정보가 포함된 파일은 커밋 전에 반드시 확인한다.
• 문서 변경이 발생한 작업은 코드와 함께 같은 커밋에 포함한다.
• 배포 절차가 확정되면 UGREEN NAS Docker 배포 방법을 이 문서에 이어서 추가한다.