From d00645214aa9e65bc4c596dde4da95811e845a40 Mon Sep 17 00:00:00 2001 From: infra Date: Mon, 15 Jun 2026 09:15:29 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=B9=8C=EB=93=9C=C2=B7=ED=85=8C?= =?UTF-8?q?=EC=8A=A4=ED=8A=B8=204=EB=8B=A8=EA=B3=84=20=EC=83=81=EC=84=B8?= =?UTF-8?q?=ED=99=94=20+=20URL=20=ED=91=9C=20+=20Coolify=20=EB=B9=8C?= =?UTF-8?q?=EB=93=9C=EB=A1=9C=EA=B7=B8/=EA=B2=B0=EA=B3=BC=ED=99=95?= =?UTF-8?q?=EC=9D=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 상단에 주소(URL) 한눈에 표(coder/gitea/coolify/minioc + 미리보기/배포 주소) - 9번: 빌드·테스트 4단계 개요표, 기동 성공 로그, npm run db:check/minio:check, 엔드포인트 기대응답 표 - 10번: podman build 로그 읽는 법(STEP/Successfully tagged), 실행/확인 단계 분리 - 12번: Coolify 빌드로그 단계(Cloning/Building/Starting)와 실패 위치별 원인, 배포주소로 엔드포인트 테스트 - FAQ: podman build 실패, Coolify Unhealthy, 옛 코드 빌드, 브라우저 미열림 Co-Authored-By: Claude Opus 4.8 --- MANUAL.md | 117 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 99 insertions(+), 18 deletions(-) diff --git a/MANUAL.md b/MANUAL.md index faacaa5..5d81041 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -9,6 +9,20 @@ DB·MinIO·AI(LiteLLM)·Git(Gitea)·배포(Coolify)가 미리 연결돼 있어, - 사내망에서 접속 가능한 브라우저 (Chrome/Edge 권장) - 본인 사번 +### 주소(URL) 한눈에 + +| 용도 | 주소 | 쓰는 곳 | +|---|---|---| +| **개발 워크스페이스** | https://coder.bokdev.in | 로그인·VS Code (1~3번) | +| **코드 저장소(Git)** | https://gitea.bokdev.in | repo 생성·push (11번) | +| **배포(Coolify)** | https://coolify.bokdev.in | 앱 빌드·배포·로그 (12번) | +| **파일저장소(MinIO 콘솔)** | https://minioc.bokdev.in | 업로드된 파일 눈으로 확인 (선택) | +| **개발 중 앱 미리보기** | `https://<자동생성>.coder.bokdev.in` | 로컬 실행 앱 브라우저 확인 (9·10번, VS Code PORTS가 자동 발급) | +| **배포된 앱 주소** | `https://` | 실제 서비스 확인 (12번) | + +> 코드에서 쓰는 주소(자동 주입, 직접 입력 불필요): **DB** `10.200.0.152:5432` · **MinIO API** `https://minio.bokdev.in` · **AI 게이트웨이** `https://litellm.bok.or.kr`. +> (콘솔 `minioc` 와 API `minio` 는 다릅니다 — 코드는 `minio`, 사람이 눈으로 볼 땐 `minioc`.) + --- ## 1. Coder 로그인 @@ -207,21 +221,51 @@ npm install # 처음 1회: 필요한 라이브러리 설치 (이걸 코드를 바로 실행해 동작을 확인하는 단계입니다(가장 빠름). +> **빌드·테스트는 4단계로 점점 "실제 배포에 가깝게" 검증합니다.** +> | 단계 | 무엇으로 | 무엇을 확인 | 어디서 | +> |---|---|---|---| +> | **9. 소스 실행** | `npm run dev` | 코드 로직 (가장 빠름) | 워크스페이스 | +> | **10. 컨테이너 빌드** | `podman build`+`run` | Dockerfile 이 제대로 빌드/기동되는지 | 워크스페이스 | +> | **11. Git push** | `git push` | 배포에 쓸 코드를 저장소에 올림 | Gitea | +> | **12. 배포 빌드** | Coolify | 실제 서비스로 빌드/기동 | Coolify | +> 앞 단계가 통과해야 뒤 단계가 거의 그대로 됩니다(같은 코드·같은 Dockerfile). 막히면 **앞 단계로 돌아가** 고치세요. + **1) 실행** ```bash cd ~/projects/<본인 프로젝트> npm run dev # 코드를 고치면 자동으로 다시 시작됨(핫리로드) ``` +실행되면 터미널에 `sample listening on :3000` 같은 줄이 뜹니다. **에러 없이** 이 줄이 보이면 기동 성공입니다. +(빨간 에러가 뜨면 거의 ① `npm install` 안 함 ② 코드 문법 오류 ③ `.project-env` 미로딩(=폴더 밖에서 실행) 셋 중 하나입니다.) -**2) 브라우저로 미리보기** — 워크스페이스는 사내 클러스터 안이라 `localhost:3000` 이 PC 브라우저엔 바로 안 열립니다. VS Code 의 포트 기능을 씁니다: +**2) 연결만 빠르게 점검**(앱 안 띄우고 DB/파일저장소 자격증명·연결 확인): +```bash +npm run db:check # → "DB OK: { now: 2026-... }" 이면 DB 연결 정상 +npm run minio:check # → "S3 OK: { bucket: 'coolify-user-data', sampleKeys: [...] }" 이면 정상 +``` +> `DB FAIL` / `S3 FAIL` 이 나오면 `.project-env` 값(host·키)을 확인하세요. **여기서 통과하면 배포 환경에서도 거의 됩니다.** + +**3) 브라우저로 미리보기** — 워크스페이스는 사내 클러스터 안이라 `localhost:3000` 이 PC 브라우저엔 바로 안 열립니다. VS Code 의 포트 기능을 씁니다: 1. VS Code 하단 **`PORTS`** 탭 클릭 → **`Forward a Port`** → 포트 번호(`3000`) 입력 (앱이 뜨면 자동 감지해 알림이 뜨기도 합니다) 2. 포워딩된 포트 옆 **🌐 (Open in Browser)** 클릭 → 새 탭에 앱이 열립니다. + - 열리는 주소: `https://<자동생성>.coder.bokdev.in` (본인 전용 임시 URL, 사내 정식 TLS) -확인 엔드포인트: `/healthz`(살아있음), `/db`(DB 연결), `/s3`(파일저장소 연결). +**4) 엔드포인트로 동작 확인** — 브라우저 주소 뒤에 경로를 붙이거나, 터미널에서 `curl` 로 확인합니다. **각 응답의 `"ok": true` 와 아래 기대값을 확인**하세요: -> 열리는 주소는 `https://<...>.coder.bokdev.in` 형태의 **본인 전용 임시 URL**(사내 정식 TLS). -> 본인만 접근 가능하고 워크스페이스를 끄면 사라집니다. **미리보기용**이며, 정식 배포는 12번입니다. +| 경로 | 의미 | 정상 응답(예) | +|---|---|---| +| `/healthz` | 앱이 살아있나 | `{"ok":true}` | +| `/db` | 내 Postgres 연결 | `{"ok":true,"now":"2026-..."}` | +| `/s3` | 파일저장소(MinIO) 연결 | `{"ok":true,"bucket":"coolify-user-data","sampleKeys":[...]}` | + +```bash +curl 127.0.0.1:3000/healthz # {"ok":true} +curl 127.0.0.1:3000/db # DB 연결 + 현재시각 +curl 127.0.0.1:3000/s3 # 버킷명 + 파일목록 일부 +``` +> `"ok": false` + `error` 가 보이면 그 메시지가 원인입니다(예: DB 비번 틀림, 버킷 없음). `/db 500` 은 보통 `.project-env` 의 `DATABASE_URL` 문제입니다. +> 이 임시 URL 은 본인만 접근 가능하고 워크스페이스를 끄면 사라집니다. **미리보기용**이며, 정식 배포는 12번입니다. --- @@ -229,25 +273,43 @@ npm run dev # 코드를 고치면 자동으로 다시 시작됨(핫 9번은 코드를 그냥 실행한 것이고, 실제 배포(Coolify)는 **Dockerfile 로 컨테이너를 빌드**해서 띄웁니다. 배포 전에 **같은 방식(컨테이너)으로 한 번 돌려보면** 배포 후 문제를 미리 잡을 수 있습니다. +(Coolify 도 똑같은 `Dockerfile` 을 쓰므로, **여기서 빌드가 되면 12번 배포 빌드도 거의 됩니다.**) +**1) 빌드** ```bash cd ~/projects/<본인 프로젝트> -podman build -t myapp . # Dockerfile 로 이미지 빌드 -podman run --rm -p 3000:3000 --env-file .project-env myapp # 컨테이너로 실행 -# 또는: podman compose up --build +podman build -t myapp . # 현재 폴더의 Dockerfile 로 이미지 빌드 ``` -(`docker` 명령도 동일하게 동작합니다 — 실제 런타임이 podman 일 뿐입니다.) +(`docker build ...` 도 동일하게 동작합니다 — 실제 런타임이 podman 일 뿐입니다.) -**동작 확인** — 컨테이너 접속 확인은 **`127.0.0.1`** 로 하세요(`localhost` 가 간혹 안 잡힙니다): +**빌드 로그 읽는 법** — 한 줄씩 `STEP 1/9`, `STEP 2/9` … 식으로 진행됩니다(이게 Dockerfile 의 각 명령). 마지막에 +``` +COMMIT myapp +Successfully tagged localhost/myapp:latest +<이미지ID> +``` +가 보이면 **빌드 성공**입니다. 빌드된 이미지는 `podman images` 로 확인할 수 있습니다. +- **실패하면** 빨간 `Error:` 줄과 **몇 번째 STEP 에서 멈췄는지**를 보세요. 가장 흔한 건 `npm ci`/`npm install` 단계 실패(=의존성 문제, `package.json` 확인)입니다. + +**2) 실행** +```bash +podman run --rm -p 3000:3000 --env-file .project-env myapp # 빌드한 이미지를 컨테이너로 실행 +# 또는 (빌드+실행 한 번에): podman compose up --build +``` +- `--env-file .project-env` 로 DB/S3 값을 컨테이너에 넣어줍니다(이게 없으면 컨테이너 안에서 `/db`·`/s3` 가 실패합니다). +- 기동되면 9번과 똑같이 `sample listening on :3000` 이 보입니다. + +**3) 동작 확인** — 컨테이너 접속 확인은 **`127.0.0.1`** 로 하세요(`localhost` 가 간혹 안 잡힙니다). 기대 응답은 9번 표와 동일합니다: ```bash curl 127.0.0.1:3000/healthz # {"ok":true} -curl 127.0.0.1:3000/db # DB 연결 확인 -curl 127.0.0.1:3000/s3 # 파일저장소 연결 확인 +curl 127.0.0.1:3000/db # {"ok":true,"now":"2026-..."} +curl 127.0.0.1:3000/s3 # {"ok":true,"bucket":"coolify-user-data",...} ``` -- 브라우저로 보려면 9번과 동일하게 **PORTS 패널 → Forward Port 3000 → Open in Browser**. +- 브라우저로 보려면 9번과 동일하게 **PORTS 패널 → Forward Port 3000 → Open in Browser**(`https://<자동생성>.coder.bokdev.in`). +- 확인이 끝나면 터미널에서 **Ctrl+C** 로 컨테이너를 멈춥니다(`--rm` 이라 자동 삭제됨). - 빌드/실행 권한은 워크스페이스에 이미 설정돼 있습니다(별도 설정 불필요). -> 여기서 잘 되면 **Coolify 배포도 거의 그대로 됩니다**(같은 Dockerfile 을 쓰기 때문). 안 되면 코드/Dockerfile 을 먼저 고치세요. +> 여기서 **빌드 성공 + 3개 엔드포인트 모두 `ok:true`** 면 Coolify 배포도 거의 그대로 됩니다. 안 되면 코드/Dockerfile 을 먼저 고치세요. --- @@ -302,12 +364,27 @@ git push -u origin main DATABASE_URL=postgresql://emp_<사번>:@10.200.0.152:5432/appdb?options=-c%20search_path%3Demp_<사번> ``` -**3) 배포 + 확인** -1. **Deploy** 클릭 → 빌드/배포 진행(로그를 보며 기다림). -2. 배포가 끝나면 Coolify가 알려주는 **앱 주소(도메인)** 로 접속 → `/healthz`, `/db`, `/s3` 가 정상인지 확인. -3. 이후 코드를 고쳐 **`git push` 하면 자동으로 다시 배포**됩니다. +**3) 배포(빌드) 실행 + 로그 보기** +1. 앱 화면에서 **Deploy** 클릭. +2. **Deployments** 탭(또는 우측 알림)에서 방금 빌드를 누르면 **빌드 로그가 실시간으로** 흐릅니다. 단계는 대략: + - `Cloning ...` (Gitea 에서 코드 받기) → `Building image ...`(여러분의 `Dockerfile` 로 빌드, 10번 podman build 와 같은 STEP 들) → `Starting container ...` → **`New container started`** / `Deployment finished` 가 보이면 **배포 성공**. +3. **실패하면 로그의 빨간 줄**을 보세요. 위치로 원인이 갈립니다: + - `Cloning` 에서 실패 → Repository URL(전체 주소) 문제 (FAQ `does not appear to be a git repository`). + - `Building` 에서 실패 → Dockerfile/의존성 문제. **10번에서 `podman build` 가 됐다면 여기서도 거의 됩니다** → 안 되면 push 한 코드가 최신인지(11번) 확인. + - 빌드는 됐는데 컨테이너가 `Unhealthy`/재시작 반복 → 보통 Env 누락(아래 4번 확인). -> 자주 막히는 것: ① Repository URL 전체주소 ② DATABASE_URL host 가 `10.200.0.152` 인지. (FAQ 참고) +**4) 배포된 앱 주소 확인 + 테스트** +1. 앱의 **Configuration → Domains**(또는 앱 상단)에 **공개 주소**가 표시됩니다. 없으면 Coolify 가 자동 도메인을 주거나, 원하는 도메인을 지정할 수 있습니다(예: `https://myapp.bokdev.in`). +2. 그 주소로 **9·10번과 똑같이** 엔드포인트를 확인합니다(브라우저 또는 PC 터미널 `curl`): + ```bash + curl https://<배포주소>/healthz # {"ok":true} ← 앱 기동 OK + curl https://<배포주소>/db # {"ok":true,"now":...} ← DB Env OK + curl https://<배포주소>/s3 # {"ok":true,"bucket":...} ← S3 Env OK + ``` + - `/healthz` 만 되고 `/db`·`/s3` 가 500 이면 → **Coolify Env 문제**(2번). `.project-env` 값과 정확히 같은지(특히 `DATABASE_URL` 의 `%20`/`%3D`) 다시 확인하고 재배포. +3. 이후 코드를 고쳐 **`git push` 하면 자동으로 다시 빌드·배포**됩니다(Deployments 에서 새 빌드 로그 확인 → 같은 주소로 재확인). + +> 자주 막히는 것: ① Repository URL 전체주소 ② `DATABASE_URL` host 가 `10.200.0.152` + 인코딩(`%20`/`%3D`) 그대로인지 ③ Env 를 앱에 저장했는지. (FAQ 참고) --- @@ -329,6 +406,10 @@ git push -u origin main - **Q. Coolify 배포가 `does not appear to be a git repository` 로 실패해요** → Repository URL 을 전체 주소(`https://gitea.bokdev.in/...git`)로 넣었는지 확인하세요(12번). - **Q. 배포한 앱에서 DB 연결이 안 돼요(`/db` 500)** → ① Coolify Env 의 `DATABASE_URL` host 가 `10.200.0.152` 인지, ② 끝의 `?options=-c%20search_path%3D...` 가 `%20`/`%3D` 까지 그대로인지 확인하세요. 직접 타이핑하다 인코딩을 빼면 깨집니다 — `.project-env` 값을 그대로 복사하는 게 가장 안전합니다(12번). 컨테이너명/내부 DNS 는 배포 환경에선 안 됩니다. - **Q. `npm run dev` 가 `Cannot find package 'express'` 로 실패해요** → 처음 1회 `npm install` 을 안 한 경우입니다. 프로젝트 폴더에서 `npm install` 후 다시 실행하세요(7번). +- **Q. `podman build` 가 `npm ci`/`npm install` 단계에서 실패해요** → 의존성 문제입니다. 먼저 워크스페이스에서 `npm install` 이 되는지 확인하고, `package.json` 에 빠진 패키지가 없는지 보세요(10번). +- **Q. Coolify 빌드는 성공했는데 앱이 안 떠요(Unhealthy/재시작 반복)** → 보통 Env 누락입니다. `/healthz` 만 확인해 보고, DB/S3 Env(2번)를 `.project-env` 그대로 넣었는지 확인 후 재배포하세요(12번). +- **Q. Coolify 가 옛날 코드로 빌드돼요** → `git push` 가 됐는지(11번), Coolify 의 Branch 가 `main` 인지 확인하세요. push 후 Deploy(또는 자동배포)를 다시 도세요. +- **Q. 빌드/실행은 됐는데 브라우저로 안 열려요** → 워크스페이스 앱은 `localhost` 가 PC 에서 안 열립니다. VS Code **PORTS → Forward 3000 → Open in Browser**(`https://<자동생성>.coder.bokdev.in`)로 여세요(9번). 배포된 앱은 Coolify 가 준 공개 주소로 엽니다(12번). - **Q. DB가 비어있어요** → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다. - **Q. K8s(쿠버네티스)는 어떻게 봐요?** → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다.