refactor: .project-env 일원화 + starter→sample 리네임

- 프로젝트 설정을 .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 <noreply@anthropic.com>
2026-06-14 19:10:14 +09:00
parent 08de45d6f6
commit 499e48f2e2
12 changed files with 101 additions and 62 deletions
--- 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/<org>/<repo>.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/스토리지/배포는 위 도구들로 충분합니다.