설치 가이드
이 가이드에서는 딸깍문서의 개발 환경을 설정하는 방법을 단계별로 안내합니다.
사전 요구사항
딸깍문서를 실행하기 위해 다음이 필요합니다:
| 요구사항 | 최소 버전 | 권장 버전 |
|---|---|---|
| Node.js | 18.0 | 20.x LTS |
| npm | 9.0 | 10.x |
| Git | 2.0 | 최신 |
API 키 준비
다음 서비스의 API 키가 필요합니다:
- Anthropic API Key: Claude AI 사용을 위해 필요
- Google OAuth 자격 증명: 소셜 로그인용 (선택)
- Supabase 프로젝트: 데이터베이스 및 스토리지
설치 단계
1. 저장소 클론
git clone https://github.com/ddalkkak/smart-docs.git
cd smart-docs
2. 의존성 설치
npm install
Bun 사용 시
Bun을 사용하면 더 빠른 설치가 가능합니다:
bun install
3. 환경 변수 설정
.env.example 파일을 복사하여 .env.local 파일을 생성합니다:
cp .env.example .env.local
.env.local 파일을 열어 다음 값을 설정합니다:
.env.local
# Anthropic AI
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
# NextAuth.js
NEXTAUTH_SECRET=your-secret-key-here
NEXTAUTH_URL=http://localhost:3000
# Google OAuth (선택)
GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxxxx
# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxxxx
SUPABASE_SERVICE_ROLE_KEY=xxxxx
4. 데이터베이스 설정
Supabase 프로젝트 생성
- Supabase Console에서 새 프로젝트 생성
- 프로젝트 설정에서 API 키 확인
.env.local에 키 추가
마이그레이션 실행
# Docker로 로컬 PostgreSQL 실행 (선택)
npm run db:up
# 마이그레이션 실행
npm run db:migrate
Docker 없이 실행
Supabase 클라우드를 직접 사용하는 경우 db:up 단계를 건너뛰고 바로 마이그레이션을 실행할 수 있습니다.
5. 개발 서버 실행
npm run dev
브라우저에서 http://localhost:3000을 열어 확인합니다.
프로젝트 구조
smart-docs/
├── src/
│ ├── app/ # Next.js App Router 페이지
│ │ ├── api/ # API 라우트
│ │ ├── document/ # 문서 편집 페이지
│ │ └── ...
│ ├── components/ # React 컴포넌트
│ ├── lib/ # 유틸리티 라이브러리
│ ├── hooks/ # 커스텀 React Hooks
│ ├── types/ # TypeScript 타입 정의
│ └── utils/ # 헬퍼 함수
├── public/ # 정적 파일
├── supabase/ # Supabase 마이그레이션
├── messages/ # i18n 번역 파일
└── docs-site/ # 기술 문서 (Docusaurus)
유용한 스크립트
| 명령어 | 설명 |
|---|---|
npm run dev | 개발 서버 시작 |
npm run build | 프로덕션 빌드 |
npm run start | 프로덕션 서버 시작 |
npm run lint | ESLint 검사 |
npm run typecheck | TypeScript 타입 검사 |
npm run db:studio | Prisma Studio 실행 |
문제 해결
일반적인 오류
ANTHROPIC_API_KEY not found
.env.local 파일에 ANTHROPIC_API_KEY가 설정되어 있는지 확인하세요.
# 환경 변수 확인
echo $ANTHROPIC_API_KEY
Database connection failed
- Supabase 프로젝트가 활성 상태인지 확인
- 환경 변수의 URL과 키가 올바른지 확인
- 네트워크 연결 확인
Port 3000 already in use
다른 포트로 실행:
npm run dev -- -p 3001
다음 단계
환경 설정이 완료되었다면 빠른 시작 가이드로 이동하세요.