docs: 매뉴얼 podman/Coolify 배포 보강 + DB host를 10.200.0.152로 통일

- MANUAL: podman 빌드(127.0.0.1 확인), Coolify 배포(git 전체URL, DATABASE_URL host=10.200.0.152), FAQ 추가
- .project-env.example: DB host coolify-db.aidev.svc → 10.200.0.152(워크스페이스/배포 공통)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.project-env.example

@@ -8,8 +8,9 @@
 #       process.env 로 바로 읽습니다(별도 dotenv 불필요). git에는 올리지 마세요(.gitignore).
 
 # --- DB (본인 전용 Postgres schema) ---
-DATABASE_URL=postgresql://emp_<사번>:<pw>@coolify-db.aidev.svc.cluster.local:5432/appdb?options=-c%20search_path%3Demp_<사번>
+# host 10.200.0.152 는 워크스페이스/Coolify 배포 양쪽에서 동일하게 도달(그대로 복붙 가능).
-PGHOST=coolify-db.aidev.svc.cluster.local
+DATABASE_URL=postgresql://emp_<사번>:<pw>@10.200.0.152:5432/appdb?options=-c%20search_path%3Demp_<사번>
+PGHOST=10.200.0.152
 PGPORT=5432
 PGDATABASE=appdb
 PGUSER=emp_<사번>

MANUAL.md

@@ -143,7 +143,7 @@ psql "$DATABASE_URL"      # 본인 전용 스키마로 바로 접속됨
 
 ## 8. 컨테이너로 실행 (podman)
 
-로컬에서 컨테이너로 돌려보기 (실제 런타임은 rootless podman, `docker` 명령도 동일):
+로컬에서 컨테이너로 돌려보기 (실제 런타임은 rootless podman, `docker` 명령도 동일하게 동작):
 ```bash
 cd ~/projects/myapp
 podman build -t myapp .
@@ -152,6 +152,13 @@ podman run --rm -p 3000:3000 --env-file .project-env myapp
 podman compose up --build
 ```
 
+> 빌드/실행에 필요한 권한은 워크스페이스에 이미 설정돼 있습니다(별도 설정 불필요).
+> 컨테이너가 뜬 뒤 접속 확인은 **`127.0.0.1`** 로 하세요(`localhost` 가 간혹 안 잡힙니다):
+> ```bash
+> curl 127.0.0.1:3000/healthz     # {"ok":true}
+> curl 127.0.0.1:3000/db          # DB 연결 확인
+> ```
+
 ---
 
 ## 9. 배포하기 (Coolify)
@@ -160,13 +167,20 @@ podman compose up --build
 
 1. 프로젝트를 Gitea repo에 push (위 6번 인증 후 `git push`).
 2. **Coolify**(https://coolify.bokdev.in) 로그인.
-3. 새 리소스 생성 → **Git 기반(해당 Gitea repo 연결)** → 빌드 방식 **Dockerfile**.
+3. 새 리소스 생성 → **Git 기반(Public)** → 빌드 방식 **Dockerfile**.
-4. Coolify의 **Environment Variables** 에 앱이 쓰는 값 입력
+   - **Repository URL 은 반드시 전체 주소**로 입력: `https://gitea.bokdev.in/<org>/<repo>.git`
-   - `DATABASE_URL`, `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` 등
+     (`<org>/<repo>` 처럼 줄여 쓰면 clone 이 실패합니다.)
-   - (로컬 `.project-env`에 있던 키들과 동일하게)
+   - Branch: `main`, Port: `3000`
-5. 배포(Deploy). 이후 push 하면 자동 재배포됩니다.
+4. Coolify의 **Environment Variables** 에 앱이 쓰는 값 입력 (앱마다 **최초 1회만**, 이후 배포엔 유지됨)
+   - `DATABASE_URL`, `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `PORT`
+   - **워크스페이스 `.project-env` 의 값을 그대로 복사해 넣으면 됩니다** (DB host 도 동일).
+     ```
+     DATABASE_URL=postgresql://emp_<사번>:<pw>@10.200.0.152:5432/appdb?options=-c search_path=emp_<사번>
+     ```
+5. 배포(Deploy). 이후 `git push` 하면 자동 재배포됩니다.
 
-> 컨테이너 포트는 `3000` 입니다. Coolify에서 도메인/포트를 매핑하세요.
+> - 설정(`.project-env`)은 git 에 올라가지 않으므로, **배포 환경값은 Coolify Environment Variables 에 입력**합니다(개발=`.project-env`, 배포=Coolify, 값은 동일).
+> - 컨테이너 포트는 `3000`. Coolify에서 도메인/포트를 매핑하세요.
 
 ---
 
@@ -185,6 +199,8 @@ podman compose up --build
 - **Q. `$DATABASE_URL` 이 비어있어요** → 프로젝트 폴더 안에서 실행했는지 확인하세요. `.project-env` 는 그 폴더에 `cd` 해야 적용됩니다(7번).
 - **Q. sample 을 고쳤는데 git pull 이 안 돼요** → sample 은 참조용(읽기 전용)입니다. `new-project <이름>` 으로 복사한 폴더에서 작업하세요(7번).
 - **Q. git push가 인증을 물어봐요** → Gitea Authorize를 한 번도 안 했을 때. 6번 참고.
+- **Q. Coolify 배포가 `does not appear to be a git repository` 로 실패해요** → Repository URL 을 전체 주소(`https://gitea.bokdev.in/...git`)로 넣었는지 확인하세요(9번).
+- **Q. 배포한 앱에서 DB 연결이 안 돼요(`/db` 500)** → Coolify Env 의 `DATABASE_URL` host 가 `10.200.0.152` 인지 확인하세요. 컨테이너명/내부 DNS 는 배포 환경에선 안 됩니다(9번).
 - **Q. DB가 비어있어요** → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다.
 - **Q. K8s(쿠버네티스)는 어떻게 봐요?** → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다.