From 499e48f2e273124e89fe07fe116e22857909a0f2 Mon Sep 17 00:00:00 2001 From: infra Date: Sun, 14 Jun 2026 19:10:14 +0900 Subject: [PATCH] =?UTF-8?q?refactor:=20.project-env=20=EC=9D=BC=EC=9B=90?= =?UTF-8?q?=ED=99=94=20+=20starter=E2=86=92sample=20=EB=A6=AC=EB=84=A4?= =?UTF-8?q?=EC=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 프로젝트 설정을 .project-env 로 통일(셸 cd 시 자동 export, 앱은 process.env 사용) - .env.example → .project-env.example, .gitignore/.dockerignore 에 .project-env 추가 - new-project 복사 흐름 기준으로 README/CLAUDE/MANUAL 갱신 - LiteLLM 키는 ~/.env(update-litellm-key)로 분리 안내 Co-Authored-By: Claude Opus 4.8 --- .dockerignore | 3 +++ .env.example | 17 --------------- .gitignore | 4 +++- .project-env.example | 28 ++++++++++++++++++++++++ CLAUDE.md | 20 ++++++++--------- Dockerfile | 2 +- MANUAL.md | 52 ++++++++++++++++++++++++++++++-------------- README.md | 20 +++++++++-------- compose.yaml | 4 ++-- package.json | 4 ++-- src/config.js | 5 +++-- src/server.js | 4 ++-- 12 files changed, 101 insertions(+), 62 deletions(-) delete mode 100644 .env.example create mode 100644 .project-env.example diff --git a/.dockerignore b/.dockerignore index 4a53217..a27bd43 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,5 +1,7 @@ node_modules npm-debug.log +.project-env +.project-env.example .env .env.* .git @@ -8,3 +10,4 @@ Dockerfile compose.yaml README.md CLAUDE.md +MANUAL.md diff --git a/.env.example b/.env.example deleted file mode 100644 index 087ffa6..0000000 --- a/.env.example +++ /dev/null @@ -1,17 +0,0 @@ -# .env.example — 복사해서 .env 로 쓰세요: cp .env.example .env -# 주의: .env 는 git에 올리지 마세요(.gitignore에 포함됨). - -# --- DB --- -# 워크스페이스에 DATABASE_URL 이 이미 export 되어 있으면 비워둬도 됨(자동 사용). -# DATABASE_URL=postgresql://emp_<사번>:@coolify-db.aidev.svc.cluster.local:5432/appdb?search_path=emp_<사번> - -# --- MinIO / S3 --- -# endpoint 는 콘솔(minioc)이 아니라 API 호스트(minio)입니다. -S3_ENDPOINT=https://minio.bokdev.in -S3_REGION=us-east-1 -S3_BUCKET=coolify-user-data -S3_ACCESS_KEY_ID=REPLACE_WITH_YOUR_MINIO_ACCESS_KEY -S3_SECRET_ACCESS_KEY=REPLACE_WITH_YOUR_MINIO_SECRET_KEY - -# --- 앱 --- -PORT=3000 diff --git a/.gitignore b/.gitignore index 43e5063..9785f64 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,9 @@ node_modules/ +# 프로젝트 설정(DB/S3 자격증명 포함) — 절대 커밋 금지 +.project-env .env .env.* -!.env.example +!.project-env.example npm-debug.log* dist/ .DS_Store diff --git a/.project-env.example b/.project-env.example new file mode 100644 index 0000000..a4983ff --- /dev/null +++ b/.project-env.example @@ -0,0 +1,28 @@ +# .project-env.example — 프로젝트 설정 예시(참조용). +# +# 실제 사용: `new-project <이름>` 명령으로 sample을 복사하면 .project-env 가 +# DB(본인 schema 자동계산)+S3 값이 채워진 채로 자동 생성됩니다. +# 이 example 을 직접 복사해 쓸 일은 거의 없습니다(수동 생성 시 참고용). +# +# 동작: 프로젝트 폴더에 cd 하면 로그인 셸이 .project-env 를 자동 export → 앱은 +# process.env 로 바로 읽습니다(별도 dotenv 불필요). git에는 올리지 마세요(.gitignore). + +# --- DB (본인 전용 Postgres schema) --- +DATABASE_URL=postgresql://emp_<사번>:@coolify-db.aidev.svc.cluster.local:5432/appdb?options=-c%20search_path%3Demp_<사번> +PGHOST=coolify-db.aidev.svc.cluster.local +PGPORT=5432 +PGDATABASE=appdb +PGUSER=emp_<사번> +PGPASSWORD= +PGOPTIONS=-c search_path=emp_<사번> + +# --- MinIO / S3 --- +# endpoint 는 콘솔(minioc)이 아니라 API 호스트(minio)입니다. +S3_ENDPOINT=https://minio.bokdev.in +S3_REGION=us-east-1 +S3_BUCKET=coolify-user-data +S3_ACCESS_KEY_ID=REPLACE_WITH_YOUR_MINIO_ACCESS_KEY +S3_SECRET_ACCESS_KEY=REPLACE_WITH_YOUR_MINIO_SECRET_KEY + +# --- 앱 --- +PORT=3000 diff --git a/CLAUDE.md b/CLAUDE.md index 181ad1e..6bcb2f6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,27 +4,27 @@ **로컬 개발/테스트는 podman**, **배포는 Coolify(Gitea push → Dockerfile 자동빌드)** 로 한다. ## 절대 규칙 -- **비밀값을 코드/커밋에 넣지 마라.** DB·MinIO 자격증명은 항상 환경변수(`.env`, 워크스페이스 env)에서만 읽는다. - `.env` 는 절대 커밋하지 않는다(`.gitignore`에 있음). 새 비밀 키가 필요하면 `.env.example` 에 placeholder만 추가. +- **비밀값을 코드/커밋에 넣지 마라.** DB·MinIO 자격증명은 항상 환경변수에서만 읽는다. + 값은 프로젝트의 `.project-env` 에 있고(프로젝트 폴더 cd 시 셸이 자동 export), 이 파일은 **절대 커밋 금지**(`.gitignore`에 있음). 참고용 예시는 `.project-env.example`. - 컨테이너는 `docker` 명령으로 실행해도 되지만 **실제 런타임은 rootless podman**이다(`docker`는 podman 별칭). - 운영 배포를 직접 하지 마라. 배포는 **git push → Coolify**가 담당한다. 너는 코드/Dockerfile만 책임진다. -## 외부 연결 (이미 워크스페이스 env로 주입됨) +## 외부 연결 (프로젝트 `.project-env` 에서 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`)를 경유. + 키는 `.project-env`의 `S3_ACCESS_KEY_ID`/`S3_SECRET_ACCESS_KEY`. 코드는 `src/s3.js`를 통해 접근. +- **LiteLLM**: AI 호출은 사내 gateway(`https://litellm.bok.or.kr`) 경유. virtual key는 워크스페이스 전역인 `~/.env`(`LITELLM_KEY`)에서 관리 — `update-litellm-key` 명령으로 입력. (프로젝트 설정 아님) ## 로컬 개발 워크플로 (podman) ```bash +# 이 폴더는 new-project 로 만들어졌고 .project-env(DB/S3)가 이미 채워져 있다. +# 폴더에 들어와 있으면 셸이 .project-env 를 자동 export 한 상태다($DATABASE_URL 등 사용 가능). 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 build -t sample . +podman run --rm -p 3000:3000 --env-file .project-env sample # 또는 podman compose up --build ``` @@ -33,7 +33,7 @@ podman compose up --build ## 배포 워크플로 (Coolify) 1. Gitea repo에 push (`main` 등 배포 브랜치). 2. Coolify가 이 **Dockerfile**로 자동 빌드/배포한다(로컬 podman 빌드와 동일 Dockerfile). -3. Coolify 쪽 Environment Variables 에 `DATABASE_URL`, `S3_*` 를 채운다(로컬 `.env`와 같은 키). +3. Coolify 쪽 Environment Variables 에 `DATABASE_URL`, `S3_*` 를 채운다(로컬 `.project-env`와 같은 키). 4. 포트는 컨테이너 `3000`. Coolify에서 도메인/포트 매핑. ## 코드 규약 diff --git a/Dockerfile b/Dockerfile index bf193dd..cf7621d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ # 로컬(podman)과 Coolify 자동빌드가 공유하는 단일 Dockerfile. -# - 로컬: podman build -t starter . && podman run --rm -p 3000:3000 --env-file .env starter +# - 로컬: podman build -t sample . && podman run --rm -p 3000:3000 --env-file .project-env sample # - 배포: Gitea push → Coolify가 이 Dockerfile로 빌드/배포 FROM node:22-alpine diff --git a/MANUAL.md b/MANUAL.md index 7a1a93b..a3a3747 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -41,7 +41,7 @@ DB·MinIO·AI(LiteLLM)·Git(Gitea)·배포(Coolify)가 미리 연결돼 있어, 1. 워크스페이스 화면에서 **`VS Code Web`** 버튼 클릭 2. 브라우저에 VS Code가 열리고, 자동으로 **`/home/coder/projects`** 폴더가 열립니다. -3. 그 안에 **`starter`** 폴더가 이미 있습니다 — 표준 프로젝트 골격입니다. +3. 그 안에 **`sample`** 폴더가 이미 있습니다 — 참조용 예제입니다(직접 고치지 말고 복사해 쓰세요, 7번 참고). > 작업 파일은 반드시 **`/home/coder/projects`** 아래에 두세요. 이 폴더만 영구 보존됩니다. > (워크스페이스를 stop/재시작해도 유지. 그 밖의 위치는 사라질 수 있습니다.) @@ -54,7 +54,7 @@ DB·MinIO·AI(LiteLLM)·Git(Gitea)·배포(Coolify)가 미리 연결돼 있어, | 항목 | 내용 | |---|---| -| **개발 도구** | Java(JDK)/Maven, Node 22, Python 3.12, git, psql | +| **개발 도구** | Java(JDK)/Maven, Node 22, Python 3.12, git, psql, `tree`, `net-tools`(netstat/ifconfig) | | **컨테이너** | `podman` (그리고 `docker` 명령도 동일하게 동작 — podman 별칭) | | **DB** | 본인 전용 Postgres 스키마에 자동 연결 (`$DATABASE_URL`) | | **VS Code 확장** | Claude Code, Codex (이미 설치됨) | @@ -68,17 +68,30 @@ Claude Code / Codex / Gemini 가 사내 AI 게이트웨이를 쓰려면 **본인 키는 **한 곳에만** 넣으면 모든 도구(CLI·확장)가 공유합니다. 1. 터미널 열기: VS Code 상단 메뉴 **Terminal → New Terminal** -2. 발급받은 본인 키를 아래처럼 한 줄 넣기 (`sk-...` 부분을 본인 키로): +2. 아래 명령을 입력하고, 안내가 나오면 발급받은 본인 키(`sk-...`)를 붙여넣습니다: ```bash - echo 'sk-여기에-본인-LiteLLM-키' > ~/.config/litellm/key + update-litellm-key ``` -3. 적용을 위해 터미널을 새로 엽니다 (또는 `source ~/.bashrc`). -4. 확인: + ``` + LiteLLM virtual key 입력 (sk-...): sk-여기에-본인-키-붙여넣기 + 키 갱신 완료 (len=25). 현재 터미널에 즉시 적용됨. + ``` + > `update-litellm-key` 는 키를 파일에 저장하고 **현재 터미널에 바로 적용**합니다. + > 터미널을 새로 열거나 `source` 할 필요가 없습니다. 키를 바꿀 때도 같은 명령을 다시 쓰면 됩니다. +3. 확인: ```bash echo $ANTHROPIC_BASE_URL # https://litellm.bok.or.kr 가 나오면 정상 claude # Claude Code CLI 실행 ``` +각 도구의 **기본 모델**은 사내 게이트웨이에 맞춰 미리 설정돼 있습니다(바꾸려면 각 설정 파일 수정): + +| 도구 | 기본 모델 | 설정 파일 | +|---|---|---| +| Claude Code | `claude-opus-4-8` | `~/.claude/settings.json` | +| Codex | `gpt-5.5` | `~/.codex/config.toml` | +| Gemini | `gemini-3.1-pro-preview` | `~/.gemini/settings.json` | + > 키는 본인 워크스페이스 안에만 저장되고, 코드/깃에는 올라가지 않습니다. > 게이트웨이 주소(`https://litellm.bok.or.kr`)는 이미 설정돼 있으니 건드릴 필요 없습니다. @@ -100,25 +113,29 @@ git clone https://gitea.bokdev.in//.git --- -## 7. 표준 프로젝트로 개발 시작하기 (starter) +## 7. 새 프로젝트 시작하기 (sample 복사) -`~/projects/starter` 는 바로 돌려볼 수 있는 Node 예제입니다. +`~/projects/sample` 은 바로 돌려볼 수 있는 Node 예제이며 **읽기 전용 참조**입니다. +직접 고치지 말고, **`new-project` 명령으로 복사**해서 본인 프로젝트를 시작하세요. ```bash -cd ~/projects/starter +new-project myapp # sample 을 ~/projects/myapp 으로 복사 + .project-env(DB/S3) 자동생성 +cd ~/projects/myapp # 폴더에 들어오면 .project-env 가 자동 적용됨($DATABASE_URL 등 사용 가능) npm install -npm run dev # http://localhost:3000 에서 실행 +npm run dev # http://localhost:3000 에서 실행 ``` 동작 확인 엔드포인트: - `GET /healthz` — 살아있는지 - `GET /db` — 내 DB(Postgres) 연결 확인 - `GET /s3` — MinIO(파일 저장소) 연결 확인 -> MinIO 키는 `starter/.env` 에 이미 채워져 있습니다. -> 새 프로젝트는 이 starter를 복사하거나, 같은 구조(Dockerfile + .env)를 따르면 배포까지 매끄럽습니다. +> **`.project-env` 가 그 프로젝트의 설정 파일입니다** (DB·S3). 값을 바꾸려면 이 파일 한 곳만 고치면 됩니다. +> 프로젝트 폴더에 들어가면(cd) 자동으로 환경변수에 반영됩니다. (git에는 올라가지 않습니다) +> LiteLLM 키만은 프로젝트가 아니라 워크스페이스 전체 공용이라 `~/.env`(5번 `update-litellm-key`)에서 관리합니다. ### 내 DB 직접 접속 ```bash +cd ~/projects/myapp # 프로젝트 폴더에서 (그래야 .project-env 가 로드됨) psql "$DATABASE_URL" # 본인 전용 스키마로 바로 접속됨 ``` @@ -128,9 +145,9 @@ psql "$DATABASE_URL" # 본인 전용 스키마로 바로 접속됨 로컬에서 컨테이너로 돌려보기 (실제 런타임은 rootless podman, `docker` 명령도 동일): ```bash -cd ~/projects/starter +cd ~/projects/myapp podman build -t myapp . -podman run --rm -p 3000:3000 --env-file .env -e DATABASE_URL="$DATABASE_URL" myapp +podman run --rm -p 3000:3000 --env-file .project-env myapp # 또는 podman compose up --build ``` @@ -146,7 +163,7 @@ podman compose up --build 3. 새 리소스 생성 → **Git 기반(해당 Gitea repo 연결)** → 빌드 방식 **Dockerfile**. 4. Coolify의 **Environment Variables** 에 앱이 쓰는 값 입력 - `DATABASE_URL`, `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` 등 - - (로컬 `.env`에 있던 키들과 동일하게) + - (로컬 `.project-env`에 있던 키들과 동일하게) 5. 배포(Deploy). 이후 push 하면 자동 재배포됩니다. > 컨테이너 포트는 `3000` 입니다. Coolify에서 도메인/포트를 매핑하세요. @@ -163,7 +180,10 @@ podman compose up --build ## 자주 묻는 것 - **Q. 파일이 사라졌어요** → `~/projects` 밖에 저장했을 가능성. 작업물은 항상 `~/projects` 아래에. -- **Q. AI 도구가 인증 오류** → `~/.config/litellm/key` 에 본인 키가 들어있는지, 터미널을 새로 열었는지 확인 (5번). +- **Q. AI 도구가 인증 오류(401)** → `update-litellm-key` 를 다시 실행해 본인 키를 입력하세요 (5번). 키가 `sk-` 로 시작하는지 확인. +- **Q. AI 도구가 `Invalid model` 오류(400)** → 인증은 됐지만 모델명이 게이트웨이에 없는 경우. 5번 표의 기본 모델명을 쓰세요. +- **Q. `$DATABASE_URL` 이 비어있어요** → 프로젝트 폴더 안에서 실행했는지 확인하세요. `.project-env` 는 그 폴더에 `cd` 해야 적용됩니다(7번). +- **Q. sample 을 고쳤는데 git pull 이 안 돼요** → sample 은 참조용(읽기 전용)입니다. `new-project <이름>` 으로 복사한 폴더에서 작업하세요(7번). - **Q. git push가 인증을 물어봐요** → Gitea Authorize를 한 번도 안 했을 때. 6번 참고. - **Q. DB가 비어있어요** → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다. - **Q. K8s(쿠버네티스)는 어떻게 봐요?** → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다. diff --git a/README.md b/README.md index 91dabe4..3b72fcf 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ -# starter — Node 앱 스타터 (podman 개발 + Coolify 배포) +# sample — Node 앱 샘플 (podman 개발 + Coolify 배포) -사내 워크스페이스용 Node(ESM) 스타터. DB·MinIO 연결, podman 로컬개발, Coolify 자동배포가 미리 잡혀 있다. +사내 워크스페이스용 Node(ESM) 샘플. DB·MinIO 연결, podman 로컬개발, Coolify 자동배포가 미리 잡혀 있다. +이 폴더(`~/projects/sample`)는 **읽기 전용 참조**다. 직접 고치지 말고, 새 작업은 아래처럼 복사해서 시작한다. -## 빠른 시작 +## 새 프로젝트 시작 ```bash +new-project myapp # sample 을 ~/projects/myapp 으로 복사 + .project-env(DB/S3) 자동생성 +cd ~/projects/myapp # 들어오면 셸이 .project-env 를 자동 export ($DATABASE_URL 등 사용 가능) npm install -cp .env.example .env # MinIO 키 채우기 (DB는 워크스페이스가 자동주입) npm run dev # http://localhost:3000 ``` - `GET /healthz` — 헬스체크 @@ -14,8 +16,8 @@ npm run dev # http://localhost:3000 ## 컨테이너로 실행 (podman) ```bash -podman build -t starter . -podman run --rm -p 3000:3000 --env-file .env -e DATABASE_URL="$DATABASE_URL" starter +podman build -t sample . +podman run --rm -p 3000:3000 --env-file .project-env sample # 또는: podman compose up --build ``` @@ -23,8 +25,8 @@ podman run --rm -p 3000:3000 --env-file .env -e DATABASE_URL="$DATABASE_URL" sta Gitea에 push → Coolify가 `Dockerfile`로 자동 빌드/배포. Coolify Env에 `DATABASE_URL`, `S3_*` 입력. ## 연결정보 -- **DB**: 워크스페이스 env `DATABASE_URL` 자동주입 (본인 schema 격리) -- **MinIO(S3)**: endpoint `https://minio.bokdev.in`, bucket `coolify-user-data`, 키는 `.env`에 직접 입력 -- **AI**: `~/.config/litellm/key` 에 LiteLLM virtual key 입력 → Claude Code/Codex/Gemini 공용 +- **DB**: 프로젝트 `.project-env` 의 `DATABASE_URL` (본인 schema 격리, 폴더 cd 시 자동 export) +- **MinIO(S3)**: endpoint `https://minio.bokdev.in`, bucket `coolify-user-data`, 키는 `.project-env`에 있음 +- **AI**: `~/.env` 의 `LITELLM_KEY`(`update-litellm-key` 명령으로 입력) → Claude Code/Codex/Gemini 공용 자세한 작업 규약은 `CLAUDE.md` 참고. diff --git a/compose.yaml b/compose.yaml index 60b8c31..82b4117 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,13 +1,13 @@ # 로컬 개발용 (podman compose 또는 podman play). 운영 배포는 Coolify가 담당. # podman compose up --build -# DB/MinIO 접속정보는 워크스페이스 env + .env 에서 주입됨. +# DB/MinIO 접속정보는 프로젝트 .project-env 에서 주입됨(프로젝트 폴더 cd 시 셸이 자동 export). services: app: build: . ports: - "3000:3000" env_file: - - .env + - .project-env environment: # 워크스페이스에 자동 주입된 값을 컨테이너로 전달 DATABASE_URL: ${DATABASE_URL} diff --git a/package.json b/package.json index c09836e..9705560 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { - "name": "starter", + "name": "sample", "version": "0.1.0", - "description": "사내 Node 스타터 — podman 로컬개발 + Coolify(Dockerfile) 배포", + "description": "사내 Node 샘플 — podman 로컬개발 + Coolify(Dockerfile) 배포", "type": "module", "main": "src/server.js", "scripts": { diff --git a/src/config.js b/src/config.js index e352b7c..daf53e2 100644 --- a/src/config.js +++ b/src/config.js @@ -1,6 +1,7 @@ // 환경설정 — 모든 외부 연결정보는 환경변수에서만 읽는다(코드에 비밀값 금지). // -// DB: 워크스페이스가 DATABASE_URL / PG* 를 자동 주입함(직원 전용 schema로 격리). +// 값의 출처: 프로젝트 폴더의 .project-env (DB 본인 schema + S3). 프로젝트 폴더에 cd 하면 +// 로그인 셸이 자동 export → 여기 process.env 로 그대로 들어온다(별도 dotenv 불필요). // MinIO(S3): 사내 오브젝트 스토리지. endpoint는 API 호스트(minio.bokdev.in), // 콘솔(minioc.bokdev.in)이 아님에 주의. // @@ -9,7 +10,7 @@ export const config = { port: parseInt(process.env.PORT || "3000", 10), - // Postgres — 워크스페이스 자동주입. Coolify에선 본인 DB 접속정보를 넣을 것. + // Postgres — .project-env 의 DATABASE_URL. Coolify에선 본인 DB 접속정보를 넣을 것. databaseUrl: process.env.DATABASE_URL || "", // MinIO / S3 호환 diff --git a/src/server.js b/src/server.js index 72b394d..e94230a 100644 --- a/src/server.js +++ b/src/server.js @@ -25,9 +25,9 @@ app.get("/s3", async (_req, res) => { }); app.get("/", (_req, res) => - res.json({ name: "starter", endpoints: ["/healthz", "/db", "/s3"] }) + res.json({ name: "sample", endpoints: ["/healthz", "/db", "/s3"] }) ); app.listen(config.port, "0.0.0.0", () => { - console.log(`starter listening on :${config.port}`); + console.log(`sample listening on :${config.port}`); });