docs: 전체 개발 흐름 단계별 재구성(개발→로컬실행→빌드→git→배포·테스트)
- 전체 흐름 한눈에 + 8 개발 / 9 로컬실행·미리보기 / 10 podman빌드점검 / 11 git / 12 Coolify배포·확인 - 각 단계 '확인(테스트)' 명시, npm install 누락 FAQ 추가, 섹션 참조 갱신 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
infra
171
MANUAL.md
171
MANUAL.md
@@ -138,7 +138,7 @@ new-project myapp # sample 을 ~/projects/myapp 으로 복사 + .project-e
|
||||
**(4) 실행** — 다시 터미널(Terminal → New Terminal)에서:
|
||||
```bash
|
||||
npm install # 처음 1회: 필요한 라이브러리 설치 (이걸 안 하면 실행이 실패합니다)
|
||||
npm run dev # 앱 실행 (미리보기는 7-2 참고)
|
||||
npm run dev # 앱 실행 (실행·미리보기는 9번 참고)
|
||||
```
|
||||
동작 확인 엔드포인트:
|
||||
- `GET /healthz` — 살아있는지
|
||||
@@ -159,17 +159,89 @@ claude # Claude Code 실행 (또는 codex / gemini)
|
||||
> 프로젝트 폴더에 들어가면(cd) 자동으로 환경변수에 반영됩니다. (git에는 올라가지 않습니다)
|
||||
> LiteLLM 키만은 프로젝트가 아니라 워크스페이스 전체 공용이라 `~/.env`(5번 `update-litellm-key`)에서 관리합니다.
|
||||
|
||||
### 내 DB 직접 접속
|
||||
```bash
|
||||
cd ~/projects/<본인 프로젝트> # 프로젝트 폴더에서 (그래야 .project-env 가 로드됨)
|
||||
psql "$DATABASE_URL" # 본인 전용 스키마로 바로 접속됨
|
||||
---
|
||||
|
||||
## 📌 전체 개발 흐름 (한눈에)
|
||||
|
||||
```
|
||||
7. 새 프로젝트 만들기 (new-project → 폴더 열기 → 설치) ← 위에서 완료
|
||||
8. 개발하기 (코드 편집 + AI + DB/S3 사용)
|
||||
9. 로컬에서 실행·확인 (npm run dev → 브라우저 미리보기)
|
||||
10. 컨테이너로 빌드·확인 (podman build/run — 배포와 동일한 방식으로 검증)
|
||||
11. Gitea에 올리기 (git push)
|
||||
12. Coolify로 배포·확인 (실제 서비스로 띄우기)
|
||||
```
|
||||
아래는 각 단계를 순서대로 설명합니다.
|
||||
|
||||
---
|
||||
|
||||
## 7-1. 프로젝트를 Gitea(git)에 올리기
|
||||
## 8. 개발하기
|
||||
|
||||
`new-project` 로 만든 폴더는 git 저장소가 아직 아닙니다(`.git` 없음). 아래처럼 올립니다.
|
||||
(7번에서 **File → Open Folder 로 본인 프로젝트 폴더를 열어 둔 상태**에서)
|
||||
|
||||
- **코드 편집**: 왼쪽 파일 목록에서 파일(예: `src/server.js`)을 눌러 수정 → **Ctrl+S 로 저장**.
|
||||
- **AI 도구 활용**: 터미널에서 `claude`(또는 `codex`/`gemini`) 실행. **반드시 프로젝트 폴더 안에서** 실행해야 그 프로젝트를 봅니다(7번 (5) 참고). 키 설정은 5번.
|
||||
- **내 DB 직접 접속**(필요 시):
|
||||
```bash
|
||||
cd ~/projects/<본인 프로젝트> # 프로젝트 폴더에서 (그래야 .project-env 가 로드됨)
|
||||
psql "$DATABASE_URL" # 본인 전용 스키마로 바로 접속됨
|
||||
```
|
||||
- **참고**: DB(`$DATABASE_URL`)·S3 접속정보는 `.project-env` 에 이미 들어 있고, 프로젝트 폴더에 들어가면 자동 적용됩니다. 코드에서는 그냥 `process.env.DATABASE_URL` 등으로 쓰면 됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 9. 로컬에서 실행하고 브라우저로 확인하기
|
||||
|
||||
코드를 바로 실행해 동작을 확인하는 단계입니다(가장 빠름).
|
||||
|
||||
**1) 실행**
|
||||
```bash
|
||||
cd ~/projects/<본인 프로젝트>
|
||||
npm run dev # 코드를 고치면 자동으로 다시 시작됨(핫리로드)
|
||||
```
|
||||
|
||||
**2) 브라우저로 미리보기** — 워크스페이스는 사내 클러스터 안이라 `localhost:3000` 이 PC 브라우저엔 바로 안 열립니다. VS Code 의 포트 기능을 씁니다:
|
||||
1. VS Code 하단 **`PORTS`** 탭 클릭 → **`Forward a Port`** → 포트 번호(`3000`) 입력
|
||||
(앱이 뜨면 자동 감지해 알림이 뜨기도 합니다)
|
||||
2. 포워딩된 포트 옆 **🌐 (Open in Browser)** 클릭 → 새 탭에 앱이 열립니다.
|
||||
|
||||
확인 엔드포인트: `/healthz`(살아있음), `/db`(DB 연결), `/s3`(파일저장소 연결).
|
||||
|
||||
> 열리는 주소는 `https://<...>.coder.bokdev.in` 형태의 **본인 전용 임시 URL**(사내 정식 TLS).
|
||||
> 본인만 접근 가능하고 워크스페이스를 끄면 사라집니다. **미리보기용**이며, 정식 배포는 12번입니다.
|
||||
|
||||
---
|
||||
|
||||
## 10. 컨테이너로 빌드해서 확인하기 (podman) — 배포 전 점검
|
||||
|
||||
9번은 코드를 그냥 실행한 것이고, 실제 배포(Coolify)는 **Dockerfile 로 컨테이너를 빌드**해서 띄웁니다.
|
||||
배포 전에 **같은 방식(컨테이너)으로 한 번 돌려보면** 배포 후 문제를 미리 잡을 수 있습니다.
|
||||
|
||||
```bash
|
||||
cd ~/projects/<본인 프로젝트>
|
||||
podman build -t myapp . # Dockerfile 로 이미지 빌드
|
||||
podman run --rm -p 3000:3000 --env-file .project-env myapp # 컨테이너로 실행
|
||||
# 또는: podman compose up --build
|
||||
```
|
||||
(`docker` 명령도 동일하게 동작합니다 — 실제 런타임이 podman 일 뿐입니다.)
|
||||
|
||||
**동작 확인** — 컨테이너 접속 확인은 **`127.0.0.1`** 로 하세요(`localhost` 가 간혹 안 잡힙니다):
|
||||
```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 # 파일저장소 연결 확인
|
||||
```
|
||||
- 브라우저로 보려면 9번과 동일하게 **PORTS 패널 → Forward Port 3000 → Open in Browser**.
|
||||
- 빌드/실행 권한은 워크스페이스에 이미 설정돼 있습니다(별도 설정 불필요).
|
||||
|
||||
> 여기서 잘 되면 **Coolify 배포도 거의 그대로 됩니다**(같은 Dockerfile 을 쓰기 때문). 안 되면 코드/Dockerfile 을 먼저 고치세요.
|
||||
|
||||
---
|
||||
|
||||
## 11. Gitea(git)에 올리기
|
||||
|
||||
`new-project` 로 만든 폴더는 아직 git 저장소가 아닙니다(`.git` 없음). 아래처럼 올립니다.
|
||||
(배포(12번)는 Gitea repo 를 받아서 빌드하므로, 배포 전에 반드시 올려야 합니다.)
|
||||
|
||||
**1) Gitea에 빈 저장소 만들기**
|
||||
- **https://gitea.bokdev.in** → 우측 상단 **`+` → New Repository**
|
||||
@@ -190,79 +262,39 @@ git push -u origin main
|
||||
- 인증은 자동입니다(6번 Gitea 승인을 한 번 했다면). 처음이면 승인 화면이 한 번 뜹니다.
|
||||
- 이후 수정한 뒤에는 `git add . && git commit -m "..." && git push` 만 반복하면 됩니다.
|
||||
|
||||
> **순서는 상관없습니다.** 코드를 먼저 만들고(권장) 나중에 저장소를 만들어도 되고, 저장소를 먼저 만들어도 됩니다. `git push` 시점에 Gitea 저장소만 있으면 됩니다.
|
||||
> **`.project-env` 는 git에 올라가지 않습니다**(DB·S3 자격증명 보호 — 정상). `git status` 에 안 보여도 맞습니다. 배포 시엔 그 값을 Coolify에 따로 넣습니다(9번).
|
||||
> **순서는 상관없습니다.** 코드를 먼저 만들고(권장) 나중에 저장소를 만들어도 됩니다. `git push` 시점에 Gitea 저장소만 있으면 됩니다.
|
||||
> **`.project-env` 는 git에 올라가지 않습니다**(DB·S3 자격증명 보호 — 정상). `git status` 에 안 보여도 맞습니다. 배포 환경값은 Coolify에 따로 넣습니다(12번).
|
||||
|
||||
---
|
||||
|
||||
## 7-2. 개발 중인 앱 미리보기 (브라우저에서 열기)
|
||||
## 12. Coolify로 배포하고 확인하기
|
||||
|
||||
`npm run dev` 로 띄운 앱(예: `:3000`)을 브라우저로 보려면 — 워크스페이스는 사내 클러스터 안에 있어
|
||||
`localhost:3000` 으로는 바로 안 열립니다. 아래 방법으로 **임시 미리보기 URL** 을 받으세요.
|
||||
운영(실제 서비스) 배포는 **Coolify**가 담당합니다. 흐름은 "**Gitea에 push → Coolify가 Dockerfile로 자동 빌드·배포**" 입니다. (먼저 11번으로 Gitea에 올려두세요.)
|
||||
|
||||
> 먼저 7번처럼 `new-project <이름>` 으로 만든 **본인 프로젝트 폴더**가 있어야 합니다.
|
||||
> (`myapp` 은 예시 이름입니다. `new-project` 로 만들지 않은 폴더는 없습니다.)
|
||||
|
||||
**VS Code 의 PORTS 패널 (가장 쉬움)**
|
||||
1. 터미널에서 본인 프로젝트 폴더로 가서 앱 실행:
|
||||
```bash
|
||||
cd ~/projects/<본인이 만든 이름> # 예: cd ~/projects/myapp
|
||||
npm run dev
|
||||
```
|
||||
2. VS Code 하단 **`PORTS`** 탭 → **`Forward a Port`** → 포트 번호(`3000`) 입력
|
||||
(앱이 뜨면 자동으로 감지해 알림이 뜨기도 합니다)
|
||||
3. 포워딩된 포트 옆 **🌐 (Open in Browser)** 클릭 → 새 탭에 앱이 열립니다.
|
||||
|
||||
> 열리는 주소는 `https://<...>.coder.bokdev.in` 형태의 **본인 전용 임시 URL** 입니다(사내 정식 TLS 적용).
|
||||
> 본인만 접근 가능하며, 워크스페이스를 끄면 사라집니다. **운영 배포가 아니라 미리보기용**입니다.
|
||||
> (정식 서비스 배포는 9번 Coolify 참고.)
|
||||
|
||||
---
|
||||
|
||||
## 8. 컨테이너로 실행 (podman)
|
||||
|
||||
로컬에서 컨테이너로 돌려보기 (실제 런타임은 rootless podman, `docker` 명령도 동일하게 동작):
|
||||
```bash
|
||||
cd ~/projects/myapp
|
||||
podman build -t myapp .
|
||||
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)
|
||||
|
||||
운영 배포는 **Coolify**가 담당합니다. 흐름은 "**Gitea에 push → Coolify가 Dockerfile로 자동 빌드·배포**" 입니다.
|
||||
|
||||
1. 프로젝트를 Gitea repo에 push (위 6번 인증 후 `git push`).
|
||||
2. **Coolify**(https://coolify.bokdev.in) 로그인.
|
||||
3. 새 리소스 생성 → **Git 기반(Public)** → 빌드 방식 **Dockerfile**.
|
||||
- **Repository URL 은 반드시 전체 주소**로 입력: `https://gitea.bokdev.in/<org>/<repo>.git`
|
||||
(`<org>/<repo>` 처럼 줄여 쓰면 clone 이 실패합니다.)
|
||||
**1) 앱 만들기**
|
||||
1. **Coolify**(https://coolify.bokdev.in) 로그인.
|
||||
2. 새 리소스 생성 → **Git 기반(Public)** → 빌드 방식 **Dockerfile**.
|
||||
- **Repository URL 은 반드시 전체 주소**로 입력: `https://gitea.bokdev.in/<본인사번>/myapp.git`
|
||||
(`<본인사번>/myapp` 처럼 줄여 쓰면 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 도 동일).
|
||||
|
||||
**2) 환경변수 입력** (앱마다 **최초 1회만**, 이후 배포엔 유지됨)
|
||||
- Coolify의 **Environment Variables** 에 입력: `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` 하면 자동 재배포됩니다.
|
||||
|
||||
> - 설정(`.project-env`)은 git 에 올라가지 않으므로, **배포 환경값은 Coolify Environment Variables 에 입력**합니다(개발=`.project-env`, 배포=Coolify, 값은 동일).
|
||||
> - 컨테이너 포트는 `3000`. Coolify에서 도메인/포트를 매핑하세요.
|
||||
**3) 배포 + 확인**
|
||||
1. **Deploy** 클릭 → 빌드/배포 진행(로그를 보며 기다림).
|
||||
2. 배포가 끝나면 Coolify가 알려주는 **앱 주소(도메인)** 로 접속 → `/healthz`, `/db`, `/s3` 가 정상인지 확인.
|
||||
3. 이후 코드를 고쳐 **`git push` 하면 자동으로 다시 배포**됩니다.
|
||||
|
||||
> 자주 막히는 것: ① Repository URL 전체주소 ② DATABASE_URL host 가 `10.200.0.152` 인지. (FAQ 참고)
|
||||
|
||||
---
|
||||
|
||||
## 10. 워크스페이스 켜고 끄기
|
||||
## 13. 워크스페이스 켜고 끄기
|
||||
|
||||
- **그만 쓸 때**: Coder 워크스페이스 화면 → **Stop** (자원 절약. 파일은 보존됩니다.)
|
||||
- **다시 쓸 때**: **Start** (수십 초 내 기동)
|
||||
@@ -277,8 +309,9 @@ 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. 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` 인지 확인하세요. 컨테이너명/내부 DNS 는 배포 환경에선 안 됩니다(12번).
|
||||
- **Q. `npm run dev` 가 `Cannot find package 'express'` 로 실패해요** → 처음 1회 `npm install` 을 안 한 경우입니다. 프로젝트 폴더에서 `npm install` 후 다시 실행하세요(7번).
|
||||
- **Q. DB가 비어있어요** → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다.
|
||||
- **Q. K8s(쿠버네티스)는 어떻게 봐요?** → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user