# 내 한의원 사이트를 세상에 공개하려면
한의원 홈페이지를 만들었으면, 환자들이 실제로 접속할 수 있게 **인터넷에 올려야** 합니다. Clinic-OS는 이 과정을 Cloudflare라는 인프라 위에서 처리합니다.
이 가이드는 **"내 사이트를 세상에 공개하기 위한 기반"**을 마련하는 과정입니다. 계정을 만들고, 연결 키(API Token)를 발급받으면 끝입니다. 나머지는 에이전트가 알아서 합니다.
---
## Cloudflare가 해주는 일
| 역할 | 경영자 관점 | 무료 범위 |
|------|-----------|----------|
| **Pages(페이지)** | 홈페이지를 빠르고 안정적으로 서비스 | 무제한 |
| **D1** | 환자, 예약, 콘텐츠 등 경영 데이터 저장 | 5GB |
| **R2 객체 스토리지(R2)** | 사진, 파일 저장소 | 10GB/월 |
> 일반적인 한의원은 무료 범위 내에서 충분히 운영됩니다. 별도 비용이 발생하지 않습니다.
---
## 1단계: 계정 만들기
1. [dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up) 접속
2. 이메일과 비밀번호 입력
3. **이메일 인증 완료** (받은편지함에서 인증 메일 클릭)
4. 무료(Free) 플랜 선택
> **중요**: 이메일 인증을 반드시 완료하세요. 인증하지 않으면 API Token 발급 시 403 오류가 발생합니다. 가입 후 Cloudflare에서 보낸 인증 메일을 확인하고 링크를 클릭하세요.
> 이미 Cloudflare 계정이 있다면 기존 계정을 그대로 사용할 수 있습니다.
---
## 2단계: API Token 발급
API Token은 에이전트가 Cloudflare에 접속할 수 있게 해주는 **열쇠**입니다.
### 토큰 만드는 법
1. [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens) 접속
2. **토큰 생성(Create Token)** 클릭
3. **커스텀 토큰 생성(Create Custom Token)** 선택
4. 토큰 이름: `Clinic-OS` (자유)
5. 권한을 아래와 같이 설정합니다:
**계정(Account) 권한 (필수 4개)**:
| 카테고리 | 권한 | 수준 |
|----------|------|------|
| 계정 설정(Account Settings) | 계정 설정(Account Settings) | **읽기(Read)** |
| Cloudflare Pages | Pages(페이지) | **편집(Edit)** |
| D1 | D1 | **편집(Edit)** |
| R2 객체 스토리지(R2 Storage) | R2 객체 스토리지(R2 Storage) | **편집(Edit)** |
> 위 4개가 홈페이지 배포·데이터·이미지 저장에 필요한 **최소 권한**입니다. 불필요한 권한은 추가하지 마세요.
> ⚙️ **Workers 스크립트(Workers Scripts) — 편집(Edit)**: 일부 배포 환경에서 필요할 수 있어 검증 중입니다. 배포 중 권한 관련 오류가 나면 그때 이 권한만 추가하세요.
> 🌐 **커스텀 도메인(예: myclinic.com) 연결 시에만 (선택)**: 위 4개에 더해 **DNS — 편집(Edit)** 과 **영역(Zone) — 읽기(Read)** 를 추가하고, "영역 리소스(Zone Resources) → 포함(Include) → 계정의 모든 영역(All zones)"을 선택하세요. 기본 배포(`*.pages.dev`)만 사용하면 필요 없습니다.
6. **계정 리소스(Account Resources)**: 본인 계정 선택
7. **요약으로 이동(Continue to summary)** → **토큰 생성(Create Token)**
8. 화면에 표시된 토큰을 복사합니다
> **중요**: 토큰은 이 화면에서 한 번만 볼 수 있습니다. 안전한 곳에 메모해두세요.
### 토큰 적용
터미널에서 아래 명령어를 입력합니다:
```bash
export CLOUDFLARE_API_TOKEN="복사한_토큰"
```
> ⚠️ **GitHub Codespaces 사용자 주의**: 위 `export` 명령은 **현재 터미널 세션에서만** 유효합니다. Codespace를 정지/재시작하면 토큰이 사라져 다시 입력해야 합니다. 영속화하려면 아래 두 가지 중 하나를 사용하세요:
>
> **방법 A — 에이전트에게 맡기기 (권장)**
>
> ```
> 이 토큰을 .env.local에 저장해줘: cf_xxxxx...
> ```
>
> 에이전트가 `.env.local` 파일에 안전하게 저장합니다. 이 파일은 `.gitignore`에 포함되어 GitHub에 푸시되지 않습니다.
>
> **방법 B — GitHub Codespaces Secrets 등록**
>
> 1. [github.com/settings/codespaces](https://github.com/settings/codespaces) 접속
> 2. **New secret** → Name: `CLOUDFLARE_API_TOKEN`, Value: 복사한 토큰
> 3. **Repository access**: 본인의 클리닉 레포 선택
> 4. 다음 Codespace 생성/재시작 시 자동으로 환경변수에 등록됨
### 연결 확인
```bash
npx wrangler whoami
```
계정 이름과 Account ID가 표시되면 정상입니다.
---
## 2.5단계: R2 스토리지 결제 카드 등록
R2 스토리지(이미지/파일 저장)를 사용하려면 Cloudflare에 결제 카드를 등록해야 합니다. **무료 범위(10GB/월) 내에서는 비용이 청구되지 않습니다.**
1. [dash.cloudflare.com](https://dash.cloudflare.com) 로그인
2. 왼쪽 메뉴에서 **R2 객체 스토리지(R2 Object Storage)** 클릭
3. "R2 시작하기(Get started with R2)" 또는 활성화 버튼 클릭
4. 결제 카드 정보 입력 (무료 범위 내 비용 없음)
> 카드를 등록하지 않으면 에이전트가 R2 버킷을 생성할 수 없어 셋업이 중단됩니다. 반드시 사전에 등록하세요.
---
## 3단계: 나머지는 에이전트가 합니다
계정과 토큰이 준비되면, 에이전트에게 이렇게 말하세요:
```
셋업 진행해줘
```
에이전트가 자동으로:
- D1 데이터베이스 생성
- R2 스토리지 생성
- 설정 파일 연결
- 초기 데이터 투입
을 처리합니다.
---
## 인증 방식 선택
| 환경 | 인증 방식 | 비고 |
|------|----------|------|
| **GitHub Codespaces** (워크숍) | **API Token** (위 2단계) | 필수. 브라우저 OAuth 불가 |
| macOS 로컬 | API Token 또는 브라우저 로그인 | 둘 다 가능 |
| Windows WSL / 서버 | **API Token** | 필수 |
> **Codespaces 사용자**: `npx wrangler login` (브라우저 OAuth)은 Codespaces에서 팝업 차단으로 실패합니다. 반드시 위의 API Token 방식을 사용하세요.
macOS 로컬에서 직접 개발하는 경우에만 브라우저 로그인도 가능합니다:
```bash
npx wrangler login
```
브라우저가 열리면 Cloudflare에 로그인하고 **Allow**를 클릭하면 됩니다.
---
## 위임 셋업을 이용하는 경우
워크샵에서 셋업을 위임받는 경우, API Token을 셋업 담당자에게 전달합니다. 위의 2단계와 동일한 방법으로 토큰을 만들어 위임 폼에 입력하면 됩니다.
> 셋업 완료 후에는 토큰을 삭제해도 됩니다. 삭제하면 더 이상 해당 토큰으로 접근할 수 없습니다.
---
## 자주 묻는 질문
### 비용이 발생하나요?
Cloudflare Free 플랜으로 충분합니다. 월 10만 요청을 초과하는 대형 사이트만 유료 플랜이 필요합니다.
### API Token이 유출되면?
즉시 [API Tokens 페이지](https://dash.cloudflare.com/profile/api-tokens)에서 해당 토큰을 삭제하세요. 삭제 즉시 접근이 차단됩니다.
### 기존 Cloudflare 계정을 사용할 수 있나요?
네. 기존 계정에 다른 사이트가 있어도 Clinic-OS를 추가로 사용할 수 있습니다.
---
## 관련 콘텐츠
- 📹 **관련 영상**: 커리큘럼 0-2. 준비물 확인 (계정 만들기)
- 📋 **커리큘럼**: Stage 1 M0에서 다룸
- 🎯 **직원 투어**: 관리자 패널에서 **설정** 투어를 시작하세요
- 직접 설치: `npm run setup:step -- --next` 실행
- 위임 셋업: HQ에서 위임 폼에 API Token 입력