공개 문서
docs/deployment.md
아래는 docs/deployment.md 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# Skoolchef Tutorial — 배포 문서
> 스쿨용 AI 바이브코딩 커리큘럼 사이트 배포 가이드
> 최종 갱신: 2026-03-11
---
## 1. 개요
| 항목 | 내용 |
|------|------|
| **프로젝트명** | Skoolchef Tutorial |
| **목적** | Cursor · Claude Code · Gemini CLI · Google Workspace CLI 커리큘럼 웹 사이트 |
| **기술 스택** | Next.js 15 (App Router), MDX, Tailwind CSS |
| **권장 배포** | Vercel (정적/하이브리드) |
---
## 2. 사전 요구사항
- **Node.js** 22.x LTS 권장 ([nodejs.org/ko](https://nodejs.org/ko))
- **pnpm** 9.x 이상 (`npm install -g pnpm`)
- **Git** (배포 연동용)
---
## 3. 로컬 빌드 및 실행
```bash
# 저장소 클론 후
cd projects/skoolchef-tutorial
# 의존성 설치
pnpm install
# 개발 서버 (로컬 확인)
pnpm dev
# → http://localhost:3000
# 프로덕션 빌드 (배포 전 로컬 검증)
pnpm build
pnpm start
# → http://localhost:3000
```
---
## 4. Vercel 배포
### 4.1 저장소 연동
1. [Vercel](https://vercel.com) 로그인 후 **Add New Project**
2. GitHub 저장소 선택 (또는 GitLab/Bitbucket)
3. **Root Directory**가 저장소 루트가 아니라면 `projects/skoolchef-tutorial` 로 지정
### 4.2 빌드 설정 (Vercel 기본값 사용 시)
| 설정 항목 | 값 |
|-----------|-----|
| **Framework Preset** | Next.js |
| **Build Command** | `pnpm build` (또는 비워두면 자동 감지) |
| **Output Directory** | (비움 — Next.js 기본) |
| **Install Command** | `pnpm install` |
Root Directory를 `projects/skoolchef-tutorial`로 둔 경우, Vercel이 해당 폴더 기준으로 `package.json`을 인식하므로 별도 설정 없이 배포 가능합니다.
### 4.3 환경 변수
**현재 버전**에서는 사이트 자체가 정적 MDX 기반이라 **배포 시 필수 환경 변수는 없습니다.**
향후 아래 기능을 켤 경우 Vercel 프로젝트 **Settings → Environment Variables**에 추가합니다.
| 변수명 | 용도 | 필수 |
|--------|------|------|
| `NEXT_PUBLIC_SITE_URL` | 사이트 절대 URL (예: `https://tutor.example.com`) | 선택 |
| `NEXT_PUBLIC_SUPABASE_URL` | Supabase 프로젝트 URL | 선택 |
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase 익명 키 | 선택 |
| `NEXT_PUBLIC_POSTHOG_KEY` | PostHog 분석 | 선택 |
> **참고:** Notion 추출(`pnpm extract-notion`)은 **로컬 또는 CI에서만** 실행하며, `NOTION_TOKEN`, `NOTION_PAGE_ID`는 Vercel에 넣지 않아도 됩니다.
### 4.4 배포 트리거
- **자동:** GitHub `main`(또는 선택한 브랜치)에 push 시 Vercel이 자동 빌드·배포
- **수동:** Vercel 대시보드에서 **Redeploy** 또는 CLI `vercel --prod`
---
## 5. 배포 후 확인
- [ ] 루트 `/` 접속 시 메인 페이지 로드
- [ ] `/courses` 챕터 목록 표시
- [ ] `/courses/[slug]` (예: `/courses/01-signup`) 본문·이미지 정상 표시
- [ ] 모바일 뷰 반응형 동작
- [ ] (선택) `output/` 내 export HTML은 배포 대상 아님 — 로컬에서만 생성·사용
---
## 6. 콘텐츠 반영(Notion → 사이트)
배포와 별개로, Notion에서 수정한 뒤 사이트에 반영하려면 **로컬 또는 CI**에서 아래를 실행한 후 커밋·푸시합니다.
1. `pnpm extract-notion` — Notion → `content/courses/*.mdx`
2. `pnpm download-images` — Notion 이미지 → `public/images/notion/`
3. `pnpm generate-index-mdx` — 목차 `content/courses/index.mdx` 갱신
4. `git add` → `git commit` → `git push` → Vercel 자동 재배포
---
## 7. 출력물(강의안 export)
다음 명령은 **배포와 무관**하며, 로컬에서 검토용 파일을 만들 때만 사용합니다.
| 명령 | 출력 |
|------|------|
| `pnpm run export-lecture-markdown` | `output/Skoolchef-Tutorial-강의안-검토용.md` |
| `pnpm run export-lecture-html` | `output/Skoolchef-Tutorial-강의안-검토용.html`, `Skoolchef-Tutorial-Lecture-Review.html` |
---
## 8. 트러블슈팅
| 현상 | 확인·조치 |
|------|-----------|
| 빌드 실패 `Module not found` | Root Directory가 `projects/skoolchef-tutorial`인지 확인, `pnpm install`이 해당 폴더에서 실행되는지 확인 |
| 이미지 404 | `pnpm download-images` 후 `public/images/notion/`이 커밋되어 있는지 확인 |
| 목차가 비어 있음 | `pnpm generate-index-mdx` 실행 후 `content/courses/index.mdx` 커밋 |
| Node 버전 오류 | Vercel에서 **Node.js Version**을 22.x로 고정 (Settings → General) |
---
## 9. 참고
- **프로젝트 가이드**: [CLAUDE.md](../CLAUDE.md)
- **문서·콘텐츠 구조**: [CLAUDE.md §2](../CLAUDE.md)
- **Notion 파이프라인**: [README.md §Notion → 사이트 반영 플로우](../README.md)
공개 문서 변환 코드 (HTML)
<h1>Skoolchef Tutorial — 배포 문서</h1>
<blockquote>
<p>스쿨용 AI 바이브코딩 커리큘럼 사이트 배포 가이드<br>최종 갱신: 2026-03-11</p>
</blockquote>
<hr>
<h2>1. 개요</h2>
<table>
<thead>
<tr>
<th>항목</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td><strong>프로젝트명</strong></td>
<td>Skoolchef Tutorial</td>
</tr>
<tr>
<td><strong>목적</strong></td>
<td>Cursor · Claude Code · Gemini CLI · Google Workspace CLI 커리큘럼 웹 사이트</td>
</tr>
<tr>
<td><strong>기술 스택</strong></td>
<td>Next.js 15 (App Router), MDX, Tailwind CSS</td>
</tr>
<tr>
<td><strong>권장 배포</strong></td>
<td>Vercel (정적/하이브리드)</td>
</tr>
</tbody></table>
<hr>
<h2>2. 사전 요구사항</h2>
<ul>
<li><strong>Node.js</strong> 22.x LTS 권장 (<a href="https://nodejs.org/ko">nodejs.org/ko</a>)</li>
<li><strong>pnpm</strong> 9.x 이상 (<code>npm install -g pnpm</code>)</li>
<li><strong>Git</strong> (배포 연동용)</li>
</ul>
<hr>
<h2>3. 로컬 빌드 및 실행</h2>
<pre><code class="language-bash"># 저장소 클론 후
cd projects/skoolchef-tutorial
# 의존성 설치
pnpm install
# 개발 서버 (로컬 확인)
pnpm dev
# → http://localhost:3000
# 프로덕션 빌드 (배포 전 로컬 검증)
pnpm build
pnpm start
# → http://localhost:3000
</code></pre>
<hr>
<h2>4. Vercel 배포</h2>
<h3>4.1 저장소 연동</h3>
<ol>
<li><a href="https://vercel.com">Vercel</a> 로그인 후 <strong>Add New Project</strong></li>
<li>GitHub 저장소 선택 (또는 GitLab/Bitbucket)</li>
<li><strong>Root Directory</strong>가 저장소 루트가 아니라면 <code>projects/skoolchef-tutorial</code> 로 지정</li>
</ol>
<h3>4.2 빌드 설정 (Vercel 기본값 사용 시)</h3>
<table>
<thead>
<tr>
<th>설정 항목</th>
<th>값</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Framework Preset</strong></td>
<td>Next.js</td>
</tr>
<tr>
<td><strong>Build Command</strong></td>
<td><code>pnpm build</code> (또는 비워두면 자동 감지)</td>
</tr>
<tr>
<td><strong>Output Directory</strong></td>
<td>(비움 — Next.js 기본)</td>
</tr>
<tr>
<td><strong>Install Command</strong></td>
<td><code>pnpm install</code></td>
</tr>
</tbody></table>
<p>Root Directory를 <code>projects/skoolchef-tutorial</code>로 둔 경우, Vercel이 해당 폴더 기준으로 <code>package.json</code>을 인식하므로 별도 설정 없이 배포 가능합니다.</p>
<h3>4.3 환경 변수</h3>
<p><strong>현재 버전</strong>에서는 사이트 자체가 정적 MDX 기반이라 <strong>배포 시 필수 환경 변수는 없습니다.</strong></p>
<p>향후 아래 기능을 켤 경우 Vercel 프로젝트 <strong>Settings → Environment Variables</strong>에 추가합니다.</p>
<table>
<thead>
<tr>
<th>변수명</th>
<th>용도</th>
<th>필수</th>
</tr>
</thead>
<tbody><tr>
<td><code>NEXT_PUBLIC_SITE_URL</code></td>
<td>사이트 절대 URL (예: <code>https://tutor.example.com</code>)</td>
<td>선택</td>
</tr>
<tr>
<td><code>NEXT_PUBLIC_SUPABASE_URL</code></td>
<td>Supabase 프로젝트 URL</td>
<td>선택</td>
</tr>
<tr>
<td><code>NEXT_PUBLIC_SUPABASE_ANON_KEY</code></td>
<td>Supabase 익명 키</td>
<td>선택</td>
</tr>
<tr>
<td><code>NEXT_PUBLIC_POSTHOG_KEY</code></td>
<td>PostHog 분석</td>
<td>선택</td>
</tr>
</tbody></table>
<blockquote>
<p><strong>참고:</strong> Notion 추출(<code>pnpm extract-notion</code>)은 <strong>로컬 또는 CI에서만</strong> 실행하며, <code>NOTION_TOKEN</code>, <code>NOTION_PAGE_ID</code>는 Vercel에 넣지 않아도 됩니다.</p>
</blockquote>
<h3>4.4 배포 트리거</h3>
<ul>
<li><strong>자동:</strong> GitHub <code>main</code>(또는 선택한 브랜치)에 push 시 Vercel이 자동 빌드·배포</li>
<li><strong>수동:</strong> Vercel 대시보드에서 <strong>Redeploy</strong> 또는 CLI <code>vercel --prod</code></li>
</ul>
<hr>
<h2>5. 배포 후 확인</h2>
<ul>
<li><input disabled="" type="checkbox"> 루트 <code>/</code> 접속 시 메인 페이지 로드</li>
<li><input disabled="" type="checkbox"> <code>/courses</code> 챕터 목록 표시</li>
<li><input disabled="" type="checkbox"> <code>/courses/[slug]</code> (예: <code>/courses/01-signup</code>) 본문·이미지 정상 표시</li>
<li><input disabled="" type="checkbox"> 모바일 뷰 반응형 동작</li>
<li><input disabled="" type="checkbox"> (선택) <code>output/</code> 내 export HTML은 배포 대상 아님 — 로컬에서만 생성·사용</li>
</ul>
<hr>
<h2>6. 콘텐츠 반영(Notion → 사이트)</h2>
<p>배포와 별개로, Notion에서 수정한 뒤 사이트에 반영하려면 <strong>로컬 또는 CI</strong>에서 아래를 실행한 후 커밋·푸시합니다.</p>
<ol>
<li><code>pnpm extract-notion</code> — Notion → <code>content/courses/*.mdx</code></li>
<li><code>pnpm download-images</code> — Notion 이미지 → <code>public/images/notion/</code></li>
<li><code>pnpm generate-index-mdx</code> — 목차 <code>content/courses/index.mdx</code> 갱신</li>
<li><code>git add</code> → <code>git commit</code> → <code>git push</code> → Vercel 자동 재배포</li>
</ol>
<hr>
<h2>7. 출력물(강의안 export)</h2>
<p>다음 명령은 <strong>배포와 무관</strong>하며, 로컬에서 검토용 파일을 만들 때만 사용합니다.</p>
<table>
<thead>
<tr>
<th>명령</th>
<th>출력</th>
</tr>
</thead>
<tbody><tr>
<td><code>pnpm run export-lecture-markdown</code></td>
<td><code>output/Skoolchef-Tutorial-강의안-검토용.md</code></td>
</tr>
<tr>
<td><code>pnpm run export-lecture-html</code></td>
<td><code>output/Skoolchef-Tutorial-강의안-검토용.html</code>, <code>Skoolchef-Tutorial-Lecture-Review.html</code></td>
</tr>
</tbody></table>
<hr>
<h2>8. 트러블슈팅</h2>
<table>
<thead>
<tr>
<th>현상</th>
<th>확인·조치</th>
</tr>
</thead>
<tbody><tr>
<td>빌드 실패 <code>Module not found</code></td>
<td>Root Directory가 <code>projects/skoolchef-tutorial</code>인지 확인, <code>pnpm install</code>이 해당 폴더에서 실행되는지 확인</td>
</tr>
<tr>
<td>이미지 404</td>
<td><code>pnpm download-images</code> 후 <code>public/images/notion/</code>이 커밋되어 있는지 확인</td>
</tr>
<tr>
<td>목차가 비어 있음</td>
<td><code>pnpm generate-index-mdx</code> 실행 후 <code>content/courses/index.mdx</code> 커밋</td>
</tr>
<tr>
<td>Node 버전 오류</td>
<td>Vercel에서 <strong>Node.js Version</strong>을 22.x로 고정 (Settings → General)</td>
</tr>
</tbody></table>
<hr>
<h2>9. 참고</h2>
<ul>
<li><strong>프로젝트 가이드</strong>: <a href="../CLAUDE.md">CLAUDE.md</a></li>
<li><strong>문서·콘텐츠 구조</strong>: <a href="../CLAUDE.md">CLAUDE.md §2</a></li>
<li><strong>Notion 파이프라인</strong>: <a href="../README.md">README.md §Notion → 사이트 반영 플로우</a></li>
</ul>