# AI DEV 포털 사용 매뉴얼 (개발자용)

사내 개발은 **AI DEV 포털(Backstage)** 에서 시작합니다. 브라우저만 있으면 됩니다.
**포털에서 앱을 만들고 → Coder에서 코딩하고 → 버튼/푸시 한 번으로 배포**까지 됩니다.
DB·파일저장소(MinIO)·AI(LiteLLM)·Git(Gitea)·배포(Kubero)가 미리 연결돼 있어, 연결정보를 직접 다룰 필요 없이 바로 이용합니다.

> 💡 가장 큰 장점: **로그인은 사번 계정 하나(SSO)**. 포털에 로그인하면 **Coder·Gitea 는 다시 로그인 없이 자동으로 열립니다.**
> Kubero 등 그 밖의 도구는 클릭 후 **로그인 화면이 한 번 더 나올 수 있습니다**(Kubero 는 같은 사번 계정으로 로그인).
> 그리고 **저장소 생성·DB 비밀번호·배포 환경변수**는 포털이 **자동으로** 처리합니다. 직접 입력할 게 거의 없습니다.

이미지 자리는 `![설명](images/파일명.png)` 로 표시해 두었습니다. 캡처 후 `backstage/images/` 에 같은 이름으로 넣으면 됩니다.

---

## 목차

**처음 한 번만 (준비)**
- [0. 준비물 / 주소표](#0-준비물) · [1. 포털 로그인](#1-포털backstage-로그인) · [2. 홈 둘러보기](#2-홈-대시보드-둘러보기)
- [4. Coder 워크스페이스 만들기](#4-coder-워크스페이스-만들기-최초-1회) · [5. VS Code 열기](#5-vs-code-열기) · [6. AI 키 입력](#6-ai-에이전트-사용-설정-최초-1회--litellm-키-입력) · [7. Git 승인](#7-gitgitea-사용--최초-1회-승인)

**앱마다 반복하는 흐름**
- [3. 포털에서 앱 만들기](#3-포털에서-앱-만들기-ai-dev-앱-만들기) → [8. 내 앱 가져오기](#8-내-앱-가져오기-open-project) → [9. 개발하기](#9-개발하기) → [10. 로컬 실행·확인](#10-로컬에서-실행하고-브라우저로-확인하기) → [11. 컨테이너 빌드·확인](#11-컨테이너로-빌드해서-확인하기-podman) → [12. Git에 올리기](#12-gitgitea에-올리기) → [13. 배포·확인](#13-배포하고-확인하기-kubero)
- [14. 워크스페이스 켜고 끄기](#14-워크스페이스-켜고-끄기) · [자주 묻는 것](#자주-묻는-것)

```
[처음 1회]  포털 로그인 → 홈 둘러보기 → Coder 워크스페이스 생성 → AI키(6) → Git승인(7)
[앱마다]   포털에서 앱 만들기(3) → 가져오기(8) → 개발(9) → 로컬확인(10) → 빌드확인(11) → push(12) → 배포확인(13)
```

---

## 0. 준비물
- 인터넷 접속 가능한 브라우저 (Chrome/Edge 권장)
- 본인 **사번** 과 비밀번호

### 주소(URL) 한눈에

| 용도 | 주소 | 쓰는 곳 | 로그인 |
|---|---|---|---|
| **포털 (시작점)** | https://backstage.bokdev.in | 앱 만들기·도구 모음 (1~3번) | 사번 SSO (1차 로그인) |
| **개발 워크스페이스** | https://coder.bokdev.in | 코딩·VS Code (4~5번) | **SSO 자동** |
| **코드 저장소(Git)** | https://gitea.bokdev.in | 코드 보관·push (12번) | **SSO 자동** |
| **배포(Kubero)** | https://kubero.bokdev.in | 배포 상태·로그 확인 (13번) | 사번 계정으로 로그인 |
| **DB 관리(OpenEverest)** | https://openeverest.bokdev.in | DB 만들기·조회 (선택) | 별도 로그인(관리자 안내) |
| **파일저장소(MinIO 콘솔)** | https://minioc.bokdev.in | 업로드된 파일 확인 (선택) | 별도 로그인(관리자 안내) |
<!-- TODO: MinIO 콘솔 로그인 방식(직원 계정/공용 자격증명) 확인 후 표기 정정 -->
<!-- TODO: OpenEverest 직원 로그인 방식(개별 계정/공용) 확인 후 표기 정정 -->
| **개발 중 앱 미리보기** | `https://<자동생성>.coder.bokdev.in` | 워크스페이스에서 실행한 앱 (10번) | 본인 전용 |
| **배포된 앱 주소** | `https://<앱이름>.playground.bokdev.in` | 실제 서비스 (13번) | 공개 |

> 코드에서 쓰는 연결정보(DB 비밀번호·S3 키 등)는 **자동으로 주입**됩니다. 직접 외울 필요 없습니다.
> (개발할 땐 `.project-env` 파일에, 배포할 땐 포털이 자동으로 넣어 줍니다.)

> 🔑 **로그인 정리**: 포털 로그인만으로 자동으로 열리는 건 **Coder·Gitea** 입니다. **Kubero** 는 클릭하면 로그인 화면이 한 번 더 나올 수 있으며 **같은 사번 계정**으로 로그인하면 됩니다. **OpenEverest·MinIO** 는 별도 계정이 필요하니 접근이 막히면 인프라 담당자에게 문의하세요.

---

## 1. Portal 로그인

1. 브라우저에서 **https://portal.bokdev.in** 접속합니다.
2. 로그인 화면에서 **사번 계정**으로 로그인합니다.
   - **아이디** = 본인 사번 (예: `2620227`)
   - **비밀번호** = 본인 비밀번호 (초기 비밀번호를 받았다면 첫 로그인 후 변경 권장)
3. 로그인은 통합 인증(SSO)으로 처리됩니다. **여기서 한 번 로그인하면 Coder·Gitea 는 다시 로그인 없이 자동으로 열립니다.** Kubero는 `OAuth로 로그인`을 눌러 로그인할 수 있습니다.

![포털 로그인 화면](images/01-login.png)

> 💡 **비밀번호 변경**: 로그인 화면(또는 계정 메뉴)의 "비밀번호 변경" 링크에서 바꿀 수 있습니다.

---

## 1. Coder 로그인

1. 브라우저에서 **https://coder.bokdev.in** 접속
2. 로그인
   - **Username**: 본인 행번 (예: `2620227`)
   - **Password**: `bok1234!!` + 본인 사번 (예: `bok1234!!2620227`)  
    → 최초 로그인 후 비밀번호를 바꾸시기 바랍니다. (우측 상단 계정 메뉴 → `Account` → `Security`)

---

## 2. 워크스페이스 만들기 (최초 1회)

워크스페이스 = 본인 전용 개발용 컨테이너(VS Code + 각종 도구가 깔린 PC).

1. 로그인하면 **Workspaces** 화면. **`Create Workspace`** 클릭 (또는 **Templates → `aidev`** 선택)
2. 설정값 입력
   - **Name**: 워크스페이스 이름 (예: `ws-aidev-<사번>` 또는 자유롭게)
   - **External Authentication** : Gitea(그대로 둠)
   - **CPU / Memory / Home disk size**: 기본값(2 Core / 4 GiB / 10 GiB)으로 두면 됩니다. 필요하면 나중에 늘릴 수 있습니다.

   * (Optional) Gitea 계정 연동
     * git 원격 계정을 사전 연동할 수 있습니다. 지금 연동하지 않아도 추후 workspace 터미널에서 연동 가능합니다.
     * `External Authentication` - `애플리케이션 승인`
     ![Gitea 계정 연동](image-1.png)

3. **`Create Workspace`** 클릭
4. 워크스페이스가 빌드됩니다 (**처음엔 이미지 다운로드로 2~5분** 걸릴 수 있습니다. VS Code Web 까지 아이콘이 표시될 때까지 기다리세요).
   - 상태가 **Running** 이 되면 준비 완료.

> 이 워크스페이스는 한번 만들면 계속 사용합니다. 한번 만들어진 워크스페이스는 가상 PC처럼 **Start** 만 누르면 됩니다.

---

## 3. VS Code 열기

1. 워크스페이스 화면에서 **`VS Code Web`** 버튼(두번째 아이콘) 클릭
2. 브라우저에 VS Code가 열리고, 자동으로 **`/home/coder/projects`** 폴더가 열립니다. (Yes. I trust the authors 클릭)
3. 그 안에 **`sample`** 폴더가 이미 있습니다 — 참조용 예제입니다(직접 고치지 말고 복사해 쓰세요, 7번 참고).

> 작업 파일은 반드시 **`/home/coder/projects`** 아래에 두세요. 이 폴더만 영구 보존됩니다.
> (워크스페이스를 stop/재시작해도 유지. 그 밖의 위치는 사라질 수 있습니다.)

---

## 4. 미리 연결된 것들 (별도 설정 불필요)

새 워크스페이스에는 아래가 자동으로 준비돼 있습니다.

| 항목 | 내용 |
|---|---|
| **개발 도구** | 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 (이미 설치됨) |
| **AI CLI** | `claude`, `codex`, `gemini` (LiteLLM 게이트웨이 연동, 아래 5번 참고) |

---

## 5. AI 에이전트 사용 설정 (최초 1회) — LiteLLM 키 입력

Claude Code / Codex / Gemini 가 사내 AI 게이트웨이를 쓰려면 **본인 LiteLLM virtual key**가 필요합니다.
키는 **한 곳에만** 넣으면 모든 도구(CLI·확장)가 공유합니다.

1. 터미널 열기: VS Code 좌상단 맨위 메뉴 버튼(작대기 3개) **Terminal → New Terminal**
2. 화면 아래 터미널 창이 나오면, 다음 명령을 입력하고, 안내가 나오면 발급받은 본인 키(`sk-...`)를 붙여넣습니다:
   ```bash
   update-litellm-key
   ```
   ```
   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 실행
   ```
   ```bash
   echo $GOOGLE_GEMINI_BASE_URL  # https://litellm.bok.or.kr 가 나오면 정상
   gemini                     # Gemini CLI 실행
   ```
   ```bash
   echo $OPENAI_BASE_URL      # https://litellm.bok.or.kr/v1 가 나오면 정상
   codex                     # Codex 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`)는 이미 설정돼 있으니 건드릴 필요 없습니다.

---

## 6. Git(Gitea) 사용 — 최초 1회 승인

코드 저장소는 사내 **Gitea**(https://gitea.bokdev.in)입니다. 토큰 입력 없이 자동 인증됩니다.

1. 터미널에서 처음 `git clone` / `git push` 등을 하면, **Gitea 승인 화면**으로 안내됩니다.
   - 또는 Coder 화면의 **`Gitea`** external auth 항목에서 **Authorize** 를 미리 눌러도 됩니다.
2. 한 번 **Authorize(승인)** 하면, 이후로는 비밀번호 입력 없이 clone/push 가 됩니다.

예:
```bash
cd ~/projects

## 만약 새로운 repo를 다운로드 하고 싶을 경우
git clone https://gitea.bokdev.in/<org>/<repo>.git

## 사용예
git clone https://gitea.bokdev.in/playground/sample.git

## 새로운 버전으로 동기화
cd ~/projects/sample
git add .
git pull
# gitea 행번 / 비밀번호
```

---
## 7. 새 프로젝트 시작하기 (sample 복사)

`~/projects/sample` 은 바로 돌려볼 수 있는 Node 예제이며 **읽기 전용 참조**입니다.
직접 고치지 말고, **`new-project` 명령으로 복사**해서 본인 프로젝트를 시작하세요.

**(1) 터미널 열기** — VS Code 상단 메뉴 **Terminal → New Terminal** (화면 아래쪽에 터미널 창이 뜹니다)

**(2) 프로젝트 만들기** — 터미널에 입력:
```bash
new-project myapp       # sample 을 ~/projects/myapp 으로 복사 + .project-env(DB/S3) 자동생성
```
> `myapp` 은 예시입니다. 원하는 이름으로 바꿔도 됩니다.

**(3) VS Code 로 그 폴더 열기** — 만든 폴더를 편집기에 띄웁니다(왼쪽 파일 목록에 보이게):
   - 상단 메뉴 **File → Open Folder…**
   - 경로 입력칸에 **`/home/coder/projects/myapp`** 입력 → **OK**
   - (또는 왼쪽 맨 위 📁 **Explorer** 아이콘 → **Open Folder** 버튼)
   - 창이 새로고침되며 왼쪽에 `myapp` 의 파일들이 보이면 성공입니다.

> 폴더를 열면 VS Code 가 그 폴더를 "작업 공간"으로 삼습니다. 이제 왼쪽 목록에서 파일을 눌러 편집하고,
> 터미널도 자동으로 그 폴더(`~/projects/myapp`)에서 시작됩니다.

**(4) 라이브러리 설치** — 다시 터미널(Terminal → New Terminal)에서:
```bash
npm install             # 처음 1회: 필요한 라이브러리 설치 (이걸 안 하면 실행이 실패합니다)
```

여기까지 하면 프로젝트 준비 완료입니다. **이제 8번부터 본격적으로 개발**하면 됩니다(코드 편집 → AI 활용 → 실행 → 배포).

> **`.project-env` 가 그 프로젝트의 설정 파일입니다** (DB·S3). 값을 바꾸려면 이 파일 한 곳만 고치면 됩니다.
> 프로젝트 폴더에 들어가면(cd) 자동으로 환경변수에 반영됩니다. (git에는 올라가지 않습니다)
> LiteLLM 키만은 프로젝트가 아니라 워크스페이스 전체 공용이라 `~/.env`(5번 `update-litellm-key`)에서 관리합니다.



## 8. 개발하기

- **코드 편집**: 왼쪽 파일 목록에서 파일(예: `src/server.js` 또는 `index.js`)을 눌러 수정 → **Ctrl+S 로 저장**.
- **AI 도구 활용**: 터미널에서 `claude`(또는 `codex`/`gemini`) 실행. **반드시 본인 프로젝트 폴더 안에서** 실행해야 그 프로젝트를 봅니다(Open Folder 해뒀으면 새 터미널은 이미 그 폴더). 키 설정은 6번.
- **내 DB 직접 접속**(필요 시):
  ```bash
  cd ~/projects/<앱이름>     # 프로젝트 폴더에서 (그래야 .project-env 가 로드됨)
  psql "$DATABASE_URL"       # 본인 전용 스키마로 바로 접속됨
  ```
- 코드에서는 그냥 `process.env.DATABASE_URL`, `process.env.S3_*` 로 쓰면 됩니다. 값은 `.project-env` 에 이미 들어 있습니다.

### 8-1. AI 도구를 잘 쓰는 법 (팁)

- **항상 프로젝트 폴더 안에서 실행**하세요. AI는 "지금 폴더"의 파일을 읽어 맥락을 잡습니다.
- **`CLAUDE.md` 를 활용**하세요. 샘플에는 프로젝트 규칙(컨테이너 개발, 배포 방식, 비밀값 금지 등)을 적은 `CLAUDE.md`가 들어 있고, AI가 자동으로 읽습니다. 규칙·주의사항을 여기에 적어두면 그대로 따릅니다.
- **구체적으로 시키세요**: "로그인 API 만들어줘" 보다 "`src/` 에 POST /login 엔드포인트 추가, 입력 검증 후 실패 시 401 반환" 처럼.
- **확인은 직접**: AI가 만든 코드도 10번(로컬 실행)·11번(컨테이너)으로 **반드시 본인이 동작 확인** 후 커밋하세요.
- 키가 안 먹으면(401) → 6번 재실행. 모델 오류(400)면 → 6번 표의 모델명.

### 8-2. bkit — AI 개발 보조 플러그인 (선택, 권장)

**bkit**(Vibecoding Kit, https://www.bkit.ai/ )은 Claude Code 에 **체계적 개발 절차(계획→설계→구현→검증)** 와 전문 스킬을 더해주는 플러그인입니다. "무엇을 만들지"만 설명하면 단계적으로 진행해 줍니다.

**설치 (최초 1회, Claude Code 안에서 입력)**
```
claude
```
```
# claude 프롬프트에서
/plugin marketplace add popup-studio-ai/bkit-claude-code
/plugin install bkit
```
> ⚠️ VS Code 확장(웹) 에서는 플러그인을 못 씁니다. 플러그인은 **터미널의 `claude` CLI**에서 쓰세요.

**자주 쓰는 명령** (Claude Code 프롬프트에 입력)
- `/pdca pm <기능이름>` — 기능 하나를 계획→구현→검증까지 한 번에. **처음엔 이거 하나면 충분.**
- 더 세밀하게: `/pdca plan` · `/pdca design` · `/pdca do` · `/pdca analyze` · `/pdca iterate`
- `/sprint` — 여러 기능을 묶은 릴리스 단위 작업 · `/control` — AI 자율도 조절.

> 세부 절차를 몰라도 됩니다 — **원하는 걸 자연어로 말하면** bkit이 알맞은 흐름을 골라 줍니다.

---

## 9. 로컬에서 실행하고 브라우저로 확인하기

코드를 바로 실행해 동작을 확인하는 단계입니다(가장 빠름).

> **배포 전, 점점 "실제 배포에 가깝게" 4단계로 검증합니다.**
> | 단계 | 무엇으로 | 무엇을 확인 | 어디서 |
> |---|---|---|---|
> | **10. 소스 실행** | `npm run dev` | 코드 로직 (가장 빠름) | 워크스페이스 |
> | **11. 컨테이너 빌드** | `podman build`+`run` | 이미지가 제대로 빌드/기동되는지 | 워크스페이스 |
> | **12. Git push** | `git push` | 배포에 쓸 코드를 저장소에 올림 | Gitea |
> | **13. 배포** | Kubero(포털) | 실제 서비스로 빌드/기동 | Kubero |
> 앞 단계가 통과하면 뒤 단계도 거의 그대로 됩니다(같은 코드). 막히면 **앞 단계로 돌아가** 고치세요.

**1) 실행**
```bash
cd ~/projects/<앱이름>
npm run dev             # 코드를 고치면 자동 재시작(핫리로드)
```
`sample listening on :3000` 같은 줄이 **에러 없이** 보이면 기동 성공입니다.
(빨간 에러면 보통 ① `npm install` 안 함 ② 코드 문법 오류 ③ 폴더 밖에서 실행해 `.project-env` 미로딩 — 셋 중 하나.)

**2) 연결만 빠르게 점검** (앱 안 띄우고 DB/파일저장소 연결만 확인):
```bash
npm run db:check        # → "DB OK: ..." 면 DB 연결 정상
npm run minio:check     # → "S3 OK: { bucket: ..., sampleKeys: [...] }" 면 정상
```
> `DB FAIL`/`S3 FAIL` 이면 `.project-env` 값을 확인하세요. **여기서 통과하면 배포 환경에서도 거의 됩니다.**

**3) 브라우저로 미리보기** — 워크스페이스는 사내 클러스터 안이라 `localhost:3000` 이 PC 브라우저에서 바로 안 열립니다. VS Code 포트 기능을 씁니다:
1. VS Code 하단 **`PORTS`** 탭 → **`Forward a Port`** → 포트 번호 `3000` 입력 (앱이 뜨면 자동 감지되기도 함).
2. 포워딩된 포트 옆 **🌐 (Open in Browser)** 클릭 → 새 탭에 앱이 열립니다.
   - 주소: `https://<자동생성>.coder.bokdev.in` (본인 전용 임시 URL)

![브라우저 미리보기](images/coder-ports-preview.png)

**4) 엔드포인트로 동작 확인** — 주소 뒤에 경로를 붙이거나 터미널 `curl` 로 확인합니다. **각 응답의 `"ok": true`** 를 보세요:

| 경로 | 의미 | 정상 응답(예) |
|---|---|---|
| `/healthz` | 앱이 살아있나 | `{"ok":true}` |
| `/db` | 내 Postgres 연결 | `{"ok":true,"now":"2026-..."}` |
| `/s3` | 파일저장소(MinIO) 연결 | `{"ok":true,"bucket":"...","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` 가 보이면 그 메시지가 원인입니다. 이 임시 URL은 본인만 접근 가능하고 워크스페이스를 끄면 사라집니다. **미리보기용**이며 정식 배포는 13번입니다.

---

## 10. 컨테이너로 빌드해서 확인하기 (podman) — 배포 전 점검

9번은 코드를 그냥 실행한 것이고, 실제 배포(Coolify)는 **Dockerfile 로 컨테이너를 빌드**해서 띄웁니다.
배포 전에 **같은 방식(컨테이너)으로 한 번 돌려보면** 배포 후 문제를 미리 잡을 수 있습니다.
(Coolify 도 똑같은 `Dockerfile` 을 쓰므로, **여기서 빌드가 되면 12번 배포 빌드도 거의 됩니다.**)

**1) 빌드**
```bash
cd ~/projects/<본인 프로젝트>
podman build -t myapp .          # 현재 폴더의 Dockerfile 로 이미지 빌드
```
(`docker build ...` 도 동일하게 동작합니다 — 실제 런타임이 podman 일 뿐입니다.)

**빌드 로그 읽는 법** — 한 줄씩 `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          # {"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**(`https://<자동생성>.coder.bokdev.in`).
- 확인이 끝나면 터미널에서 **Ctrl+C** 로 컨테이너를 멈춥니다(`--rm` 이라 자동 삭제됨).
   * 종료되지 않는 경우
      ```bash
      podman ps
      podman stop {이름 또는 ID}
      ```

- 빌드/실행 권한은 워크스페이스에 이미 설정돼 있습니다(별도 설정 불필요).

> 여기서 **빌드 성공 + 3개 엔드포인트 모두 `ok:true`** 면 Coolify 배포도 거의 그대로 됩니다. 안 되면 코드/Dockerfile 을 먼저 고치세요.

---

## 11. Gitea(git)에 올리기

`new-project` 로 만든 폴더는 아직 git 저장소가 아닙니다(`.git` 없음). 아래처럼 올립니다.
(배포(12번)는 Gitea repo 를 받아서 빌드하므로, 배포 전에 반드시 올려야 합니다.)

> 아래 명령의 `myapp` 은 **본인이 `new-project` 로 만든 프로젝트 이름**으로 바꿔 쓰세요.

**1) Gitea에 빈 저장소 만들기**
- **https://gitea.bokdev.in** → 우측 상단 **`+` → New Repository**
- Repository Name 입력(예: `myapp`)
- **README/.gitignore/License 는 체크하지 마세요**(빈 저장소여야 충돌이 없습니다) → Create
- 생성되면 주소가 나옵니다: `https://gitea.bokdev.in/<본인사번>/myapp.git`

**2) 워크스페이스 터미널에서 올리기**
```bash
cd ~/projects/myapp
git init
git add .
git commit -m "first commit(혹은 자유롭게)"
git branch -M main
git remote add origin https://gitea.bokdev.in/<본인사번>/myapp.git
git push -u origin main
```

- 인증은 자동입니다(6번 Gitea 승인을 한 번 했다면). 처음이면 승인 화면이 한 번 뜹니다.
- 이후 수정한 뒤에는 `git add . && git commit -m "..." && git push` 만 반복하면 됩니다.

> **순서는 상관없습니다.** 코드를 먼저 만들고(권장) 나중에 저장소를 만들어도 됩니다. `git push` 시점에 Gitea 저장소만 있으면 됩니다.
> **`.project-env` 는 git에 올라가지 않습니다**(DB·S3 자격증명 보호 — 정상). `git status` 에 안 보여도 맞습니다.

---

## 12. 배포하고 확인하기 (Kubero)

배포는 **Kubero**가 담당합니다. 좋은 소식: 3번에서 **"생성 직후 Kubero 로 배포"를 켰다면 배포 통로가 이미 자동으로 설정**돼 있습니다. 그래서 개발자가 할 일은 사실상 **`git push`(12번)** 뿐입니다.

### 자동 배포 (TODO: 현재 안됨)

1. 12번처럼 **`git push`** 합니다.
2. Kubero가 변경을 감지해 **자동으로 다시 빌드·배포**합니다(환경변수도 사번 기준으로 **자동 주입** — 직접 넣을 필요 없음).
3. 잠시 후 아래 주소로 확인합니다:
   ```
   https://<앱이름>.playground.bokdev.in
   ```
   ```bash
   curl https://<앱이름>.playground.bokdev.in/healthz   # {"ok":true}      ← 앱 기동 OK
   curl https://<앱이름>.playground.bokdev.in/db        # {"ok":true,...}   ← DB 연결 OK
   curl https://<앱이름>.playground.bokdev.in/s3        # {"ok":true,...}   ← S3 연결 OK
   ```

![배포된 앱](images/08-deployed-app.png)

### 나중에 배포 (3번에서 deployNow 를 껐던 경우)

- 개발이 끝난 뒤 포털의 **"AI DEV 앱 만들기"** 흐름에서 배포 옵션을 켜 실행하거나, **Kubero**(https://kubero.bokdev.in) 화면에서 해당 앱의 빌드를 실행합니다.
- 한 번 배포되어 통로가 연결된 뒤에는, 이후 `git push` 시 **자동 재배포**됩니다.

### 배포 상태·로그 보기 (Kubero)

- 홈에서 **Kubero** 카드 클릭(로그인 화면이 나오면 **같은 사번 계정**으로 로그인) → 해당 **앱(파이프라인)** 선택 → **빌드/배포 로그** 확인.
- 로그에 `listening on :3000` 비슷한 줄이 보이고 상태가 정상이면 배포 성공입니다.

### ⚠️ 배포 직후 1~2분은 "준비 중"이 정상

- 이 플랫폼은 배포·재시작할 때 컨테이너가 뜨면서 **코드를 내려받고 설치(npm install)** 한 뒤 실행합니다.
- 그래서 **배포 직후·재시작 직후 약 1~2분** 동안 주소가 404/에러로 보일 수 있습니다. **정상입니다.**
- `/healthz` 를 새로고침하며 기다리세요. `{"ok":true}` 가 뜨면 준비 완료.
- "앱이 안 떠요"의 대부분은 이 **준비 시간(init)** 타이밍 문제입니다.

> 자주 막히는 것: ① `git push` 가 됐는지(12번) ② 배포 직후 1~2분 기다렸는지 ③ `/db`·`/s3` 가 500이면 10번 로컬에서 먼저 통과했는지.

---

## 자주 묻는 것

- **Q. 로그인을 서비스마다 다시 해야 하나요?** → **Coder·Gitea 는** 포털 로그인만으로 자동 로그인됩니다(SSO). **Kubero** 는 클릭 후 로그인 화면이 한 번 더 나올 수 있으나 **같은 사번 계정**으로 들어가면 됩니다. **OpenEverest·MinIO** 는 별도 로그인이라 접근이 막히면 인프라 담당자에게 문의하세요.
- **Q. 저장소를 직접 만들어야 하나요?** → 아니요. **3번 포털에서 앱을 만들면 Gitea 저장소가 자동 생성**됩니다. `open-project <앱이름>`(8번)으로 가져오기만 하면 됩니다.
- **Q. 배포할 때 DB 비밀번호·환경변수를 입력해야 하나요?** → 아니요. 배포 시 **사번 기준으로 자동 주입**됩니다. 코드에는 비밀값을 넣지 마세요.
- **Q. 내가 만든 앱 목록은 어디서 보나요?** → 포털 **Catalog**(`/catalog`). 코드는 **Gitea**, 실행 상태/로그는 **Kubero**.
- **Q. 파일이 사라졌어요** → `~/projects` 밖에 저장했을 가능성. 작업물은 항상 `~/projects` 아래에 두세요(5번).
- **Q. AI 도구가 인증 오류(401)** → `update-litellm-key` 를 다시 실행해 본인 키를 입력하세요(6번). 키가 `sk-` 로 시작하는지 확인.
- **Q. AI 도구가 `Invalid model` 오류(400)** → 모델명이 게이트웨이에 없는 경우. 6번 표의 기본 모델명을 쓰세요.
- **Q. `$DATABASE_URL` 이 비어있어요** → 프로젝트 폴더 안에서 실행했는지 확인하세요. `.project-env` 는 그 폴더에 `cd` 해야 적용됩니다(8번).
- **Q. `npm run dev` 가 `Cannot find package ...` 로 실패해요** → 처음 1회 `npm install` 을 안 한 경우입니다. 폴더에서 `npm install` 후 다시 실행(8번).
- **Q. git push가 인증을 물어봐요** → Gitea Authorize를 한 번도 안 했을 때. 7번 참고.
- **Q. 배포 주소가 404 예요** → ① 배포 직후 1~2분(준비 시간)인지 먼저 확인 ② `/healthz` 로 상태 확인 ③ 그래도 안 되면 Kubero에서 빌드/배포 로그 확인(13번).
- **Q. `/healthz` 는 되는데 `/db`·`/s3` 가 500 이에요** → 먼저 10번(로컬)에서 `npm run db:check`/`minio:check` 가 통과하는지 확인하세요. 로컬에서 되면 배포에서도 자동 주입으로 거의 됩니다. 안 되면 Kubero 로그의 에러 메시지를 보세요.
- **Q. 배포된 앱 주소가 안 열려요(인증서 경고 등)** → 배포 주소는 **`<앱이름>.playground.bokdev.in`** 형식입니다. 미리보기(`*.coder.bokdev.in`, 10번)와는 다른 대역이니 헷갈리지 마세요.
- **Q. Kubero가 옛날 코드로 떠 있어요** → `git push`(12번)가 됐는지 확인하고, 1~2분 기다린 뒤 다시 확인하세요. 필요하면 Kubero에서 빌드를 다시 도세요.
- **Q. DB가 비어있어요** → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다.
- **Q. K8s(쿠버네티스)는 어떻게 봐요?** → 직원은 K8s에 직접 접근하지 않습니다. 포털·Coder·Kubero로 충분합니다.

---

문의: 인프라 담당자