시작하기¶
이 문서는 DataSketchers 모노레포에서 로컬 개발 환경을 구성하고
마케팅 사이트(apps/site)와 이 위키(apps/wiki)를 띄우는 방법을 안내합니다.
사전 요구사항¶
- Node.js 20+ 및 pnpm 9+ (코어패키지는 저장소의
package.json에서 확인) - Go 1.22+ (API 백엔드용,
apps/api) - Git 및 git-lfs (일부 대용량 에셋 관리)
pnpm 워크스페이스
저장소는 pnpm 워크스페이스 단일 모노레포입니다.
모든 패키지는 루트에서 pnpm install 한 번으로 설치됩니다.
1. 저장소 클론 & 의존성 설치¶
# 운영 소스 주소는 .env 의 REPO_URL 한 곳에서 관리한다 (하드코딩하지 않음).
git clone [email protected]:data-sketchers/data-sketchers-team-land-v3.git
cd data-sketchers-team-land-v3
pnpm install
프로덕션 환경변수
로컬 개발에서는 NODE_ENV가 production으로 잡혀 있으면 Astro가 조건부 로직을
프로덕션 경로로 처리해 예상과 다르게 동작할 수 있습니다.
개발용 명령 실행 전에 반드시 unset NODE_ENV 하세요. (자세한 내용은
CI/CD 문서 참고)
2. 마케팅 사이트 실행 (Astro)¶
i18n 동작 방식
Astro는 prefixDefaultLocale: false 옵션으로 한국어를 기본 경로(/)에 배치하고,
영어를 /en 접두사로 서빙합니다. 정적이므로 빌드 시 두 언어가 모두 프리랜더링됩니다.
3. API 백엔드 실행 (Go)¶
cd apps/api
cp .env.example .env # 필요 시 환경변수 채움
go run ./cmd/api
# 기본 포트 8080, 헬스체크: http://localhost:8080/health
API는 Chi 라우터 + SQLite 스토리지 + S3(에셋) 구성을 갖습니다. 구체적인 엔드포인트는 아키텍처를 참고하세요.
Go 의존성
go mod tidy 를 실행해야 새 의존성이 반영됩니다.
루트 pnpm install과 별개로 Go 모듈은 apps/api/go.sum으로 관리됩니다.
4. 이 위키 실행 (MkDocs)¶
디렉터리 구조¶
| 경로 | 설명 |
|---|---|
apps/site |
Astro 5 마케팅 사이트 (KO/EN, 정적) |
apps/api |
Go 백엔드 (Chi + SQLite + S3) |
apps/wiki |
이 위키 (Material for MkDocs) |
apps/blog |
Astro 블로그 (GitLab Pages 배포) |
infra/ |
docker-compose, nginx, 배포 관련 설정 |
scripts/ |
빌드/배포 보조 스크립트 |
prompt/docs |
프롬프트 및 문서 초안 |
첫 기여 체크리스트¶
- 저장소를 클론하고
pnpm install완료 -
unset NODE_ENV후pnpm --filter site dev로 사이트 확인 - 새 문서를 작성했다면
foo.md+foo.en.md쌍으로 작성 - 로컬에서
mkdocs serve로 위키 링크/문법 검증 -
pnpm lint(또는 저장소 lint 스크립트) 통과 - GitLab에 브랜치 push 후 Merge Request 생성
- CI 파이프라인(lint → build-image → deploy)이 녹색 통과 확인
문서 언어 규칙
위키를 비롯한 모든 문서의 한국어 페이지가 기본입니다. 누락된 영어 twin은 CI에서 오류로 감지될 수 있으니 항상 쌍으로 유지하세요.