From d85089c96b7fbf2bdbb1bbe44dc65cdaf5b1ebd2 Mon Sep 17 00:00:00 2001 From: infra Date: Sun, 14 Jun 2026 22:57:42 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=A7=A4=EB=89=B4=EC=96=BC=20podman/Co?= =?UTF-8?q?olify=20=EB=B0=B0=ED=8F=AC=20=EB=B3=B4=EA=B0=95=20+=20DB=20host?= =?UTF-8?q?=EB=A5=BC=2010.200.0.152=EB=A1=9C=20=ED=86=B5=EC=9D=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .project-env.example | 5 +++-- MANUAL.md | 30 +++++++++++++++++++++++------- 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/.project-env.example b/.project-env.example index a4983ff..5e53b93 100644 --- a/.project-env.example +++ b/.project-env.example @@ -8,8 +8,9 @@ # 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 +# host 10.200.0.152 는 워크스페이스/Coolify 배포 양쪽에서 동일하게 도달(그대로 복붙 가능). +DATABASE_URL=postgresql://emp_<사번>:@10.200.0.152:5432/appdb?options=-c%20search_path%3Demp_<사번> +PGHOST=10.200.0.152 PGPORT=5432 PGDATABASE=appdb PGUSER=emp_<사번> diff --git a/MANUAL.md b/MANUAL.md index a3a3747..84bd695 100644 --- a/MANUAL.md +++ b/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**. -4. Coolify의 **Environment Variables** 에 앱이 쓰는 값 입력 - - `DATABASE_URL`, `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` 등 - - (로컬 `.project-env`에 있던 키들과 동일하게) -5. 배포(Deploy). 이후 push 하면 자동 재배포됩니다. +3. 새 리소스 생성 → **Git 기반(Public)** → 빌드 방식 **Dockerfile**. + - **Repository URL 은 반드시 전체 주소**로 입력: `https://gitea.bokdev.in//.git` + (`/` 처럼 줄여 쓰면 clone 이 실패합니다.) + - Branch: `main`, Port: `3000` +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_<사번>:@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/스토리지/배포는 위 도구들로 충분합니다.