43 lines
2.7 KiB
Markdown
43 lines
2.7 KiB
Markdown
# CLAUDE.md — 이 프로젝트에서 Claude Code가 따라야 할 규약
|
|
|
|
너는 사내 개발 워크스페이스에서 동작하는 코딩 에이전트다. 이 프로젝트는 **Node(ESM) 앱**이고,
|
|
**로컬 개발/테스트는 podman**, **배포는 Coolify(Gitea push → Dockerfile 자동빌드)** 로 한다.
|
|
|
|
## 절대 규칙
|
|
- **비밀값을 코드/커밋에 넣지 마라.** DB·MinIO 자격증명은 항상 환경변수(`.env`, 워크스페이스 env)에서만 읽는다.
|
|
`.env` 는 절대 커밋하지 않는다(`.gitignore`에 있음). 새 비밀 키가 필요하면 `.env.example` 에 placeholder만 추가.
|
|
- 컨테이너는 `docker` 명령으로 실행해도 되지만 **실제 런타임은 rootless podman**이다(`docker`는 podman 별칭).
|
|
- 운영 배포를 직접 하지 마라. 배포는 **git push → Coolify**가 담당한다. 너는 코드/Dockerfile만 책임진다.
|
|
|
|
## 외부 연결 (이미 워크스페이스 env로 주입됨)
|
|
- **Postgres**: `DATABASE_URL` (직원 전용 schema로 격리, `search_path` 고정). 코드는 `src/db.js`를 통해 접근.
|
|
- **MinIO(S3)**: API endpoint `https://minio.bokdev.in` (콘솔 `minioc`가 아님), 버킷 `coolify-user-data`.
|
|
키는 직원이 `.env`의 `S3_ACCESS_KEY_ID`/`S3_SECRET_ACCESS_KEY`에 채운다. 코드는 `src/s3.js`를 통해 접근.
|
|
- **LiteLLM**: AI 호출은 `~/.config/litellm/key` 의 virtual key를 쓰는 사내 gateway(`https://litellm.bok.or.kr`)를 경유.
|
|
|
|
## 로컬 개발 워크플로 (podman)
|
|
```bash
|
|
npm install
|
|
cp .env.example .env # 그리고 MinIO 키 등 채우기 (DB는 자동주입이면 비워둬도 됨)
|
|
npm run dev # node --watch 로 핫리로드, http://localhost:3000
|
|
|
|
# 컨테이너로 동일하게 돌려보기
|
|
podman build -t starter .
|
|
podman run --rm -p 3000:3000 --env-file .env \
|
|
-e DATABASE_URL="$DATABASE_URL" starter
|
|
# 또는
|
|
podman compose up --build
|
|
```
|
|
연결 확인: `npm run db:check`, `npm run minio:check`, 또는 `/db` `/s3` 엔드포인트.
|
|
|
|
## 배포 워크플로 (Coolify)
|
|
1. Gitea repo에 push (`main` 등 배포 브랜치).
|
|
2. Coolify가 이 **Dockerfile**로 자동 빌드/배포한다(로컬 podman 빌드와 동일 Dockerfile).
|
|
3. Coolify 쪽 Environment Variables 에 `DATABASE_URL`, `S3_*` 를 채운다(로컬 `.env`와 같은 키).
|
|
4. 포트는 컨테이너 `3000`. Coolify에서 도메인/포트 매핑.
|
|
|
|
## 코드 규약
|
|
- ESM(`import`/`export`), Node 22+. 외부 연결정보는 반드시 `src/config.js` 한 곳을 거친다.
|
|
- 새 외부 의존성을 추가하면 `package.json`에 반영하고 `npm install`로 lock 갱신.
|
|
- 변경 후에는 `npm run db:check` / `npm run minio:check`로 연결이 살아있는지 스스로 확인하라.
|