diff --git a/README.md b/README.md new file mode 100644 index 0000000..04229fb --- /dev/null +++ b/README.md @@ -0,0 +1,295 @@ +# AI DEV 개발·배포 매뉴얼 (개발자용) + +사번 계정(SSO) 하나로 로그인하여 **Coder에서 개발**하고, **Gitea에 push**, **Kubero로 배포**합니다. +DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM)는 워크스페이스에 미리 연결되어 있습니다. + +문서 원본: https://gitea.bokdev.in/playground/MANUAL + + + +## 목차 + +**최초 1회** +[1. 로그인](#1-로그인) → [2. 워크스페이스 만들기](#2-워크스페이스-만들기-최초-1회) → [3. VS Code 열기](#3-vs-code-열기) → [5. AI 키 등록](#5-ai-키-등록-최초-1회) + +**앱마다** +[6. 새 프로젝트 시작](#6-새-프로젝트-시작) → [7. 개발](#7-개발) → [8. 로컬 실행·확인](#8-로컬-실행확인) → [9. 배포](#9-배포-gitea--kubero) + +``` +[최초 1회] 로그인(1) → 워크스페이스 생성(2) → VS Code(3) → AI 키 등록(5) +[앱마다] new-project + git init(6) → 개발·커밋(7) → 로컬 확인(8) → 레포 생성·push·Kubero 배포(9) +``` + +## 0. 서비스 주소 + +| 용도 | 주소 | +|---|---| +| AI DEV 포털 (시작점) | https://portal.bokdev.in | +| Coder (개발 워크스페이스) | https://coder.bokdev.in | +| Gitea (코드 저장소) | https://gitea.bokdev.in | +| Kubero (배포) | https://kubero.bokdev.in | +| 개발 중 미리보기 | `https://<자동생성>.coder.bokdev.in` | +| 배포된 앱 | `https://<레포명>.playground.bokdev.in` | + +모든 서비스는 **사번 계정(SSO)** 으로 로그인합니다. + +코드에서 쓰는 접속정보(DB·S3)는 `.project-env` 파일로 자동 제공됩니다. 직접 입력할 값이 없습니다. + +## 1. 로그인 + +1. https://portal.bokdev.in 접속 + +2. 사번 계정으로 로그인 + - 아이디: 본인 사번 (예: `2620227`) + - 비밀번호: 본인 비밀번호 (초기 비밀번호는 첫 로그인 후 변경) +3. 이후 Coder·Gitea·Kubero는 추가 로그인 없이 같은 계정으로 열립니다. + +![포털 로그인 화면](images/01-login.png) + +비밀번호 변경: 로그인 화면의 "비밀번호 변경" 링크. + +## 2. 워크스페이스 만들기 (최초 1회) + +워크스페이스 = 본인 전용 개발 컨테이너(VS Code + 개발 도구 일체). + +1. https://coder.bokdev.in → **Workspaces** → **Create Workspace** (템플릿: `aidev`) +2. 설정값 입력 + - **Name**: 워크스페이스 이름 (예: `ws-aidev-<사번>`) + - **External Authentication**: Gitea — **애플리케이션 승인** 클릭 + - **CPU / Memory / Disk**: 기본값(2 Core / 4 GiB / 10 GiB) 사용. 추후 변경 가능. + + ![Gitea 계정 연동](image-1.png) + +3. **Create Workspace** 클릭 +4. 최초 빌드는 2~5분 소요. 상태가 **Running**이 되면 완료. + +> **주의**: 같은 브라우저에 다른 계정으로 Gitea 로그인이 남아 있으면 그 계정으로 연동됩니다. +> 승인 전에 Gitea에서 로그아웃했는지 확인하거나, 시크릿 창에서 진행합니다. + +워크스페이스는 한 번 만들면 계속 사용합니다. 이후에는 **Start**만 누르면 됩니다([10번](#10-coder-workspace-켜고-끄기)). + +## 3. VS Code 열기 + +1. 워크스페이스 화면에서 **VS Code Web** 아이콘 클릭 +2. `/home/coder/projects` 폴더가 자동으로 열립니다. ("Yes, I trust the authors" 클릭) +3. 안에 **`sample`** 폴더가 있습니다. DB·S3 연결이 확인된 참조용 예제이며 **직접 수정하지 않습니다**. [6번](#6-새-프로젝트-시작)에서 복사해 사용합니다. + + +> 작업 파일은 반드시 `/home/coder/projects` 아래에 둡니다. 이 폴더만 워크스페이스 재시작 후에도 보존됩니다. + +## 4. 기본 제공 환경 + +새 워크스페이스에 아래가 설치·연결되어 있습니다. + +| 항목 | 내용 | +|---|---| +| 개발 도구 | Java(JDK)/Maven, Node 22, Python 3.12, git, psql | +| 컨테이너 | podman (`docker` 명령도 동일 동작) | +| DB | 본인 전용 PostgreSQL 스키마 (`$DATABASE_URL`) | +| VS Code 확장 | Claude Code, Codex | +| AI CLI | `claude`, `codex` — [5번](#5-ai-키-등록-최초-1회)에서 키 등록 필요 | + +## 5. AI 키 등록 (최초 1회) + +Claude Code / Codex 는 사내 AI 게이트웨이(LiteLLM)를 사용합니다. 발급받은 본인 virtual key를 한 번만 등록하면 CLI·확장이 모두 공유합니다. + +1. 터미널 열기: VS Code 메뉴(좌상단 ☰) → **Terminal → New Terminal** +2. 아래 명령 실행 후 본인 키(`sk-...`) 입력: + ```bash + update-litellm-key + ``` + ``` + LiteLLM virtual key 입력 (sk-...): sk-본인-키 + 키 갱신 완료 (len=25). 현재 터미널에 즉시 적용됨. + ``` +3. 확인: + ```bash + echo $ANTHROPIC_BASE_URL # https://litellm.bok.or.kr 이면 정상 + claude + ``` + ```bash + echo $OPENAI_BASE_URL # https://litellm.bok.or.kr/v1 이면 정상 + codex + ``` + +> **키 등록·변경 후 VS Code(웹)가 응답하지 않을 수 있습니다.** +> 워크스페이스 화면에서 VS Code 서버를 **Stop → Start** 하여 재시작합니다. + +키는 워크스페이스의 `~/.env`에만 저장됩니다. 키를 바꿀 때도 같은 명령을 다시 실행합니다. + +기본 모델은 게이트웨이에 맞춰 설정되어 있습니다. + +| 도구 | 기본 모델 | 설정 파일 | +|---|---|---| +| Claude Code | `claude-opus-4-8` | `~/.claude/settings.json` | +| Codex | `gpt-5.5` | `~/.codex/config.toml` | + +## 6. 새 프로젝트 시작 + +`sample` 예제를 복사해 시작합니다. + +**(1) 터미널에서 프로젝트 생성** — 반드시 `~/projects` 에서 실행: +```bash +cd ~/projects +cd sample && git pull && cd .. # 예제 최신화 +new-project myapp # 예제를 ~/projects/myapp 으로 복사 + .project-env 자동 생성 +``` +`myapp`은 예시입니다. 이 이름은 Gitea 레포명으로 설정할 이름과 동일하게 맞추시면 되고, 소문자·숫자·하이픈만 사용합니다. + +**(2) git 초기화** — 개발 시작 시점에 합니다. 커밋 이력을 처음부터 관리하기 위함이며, 원격(Gitea) 연결은 배포 단계([9번](#9-배포-gitea--kubero))에서 합니다: +```bash +cd ~/projects/myapp +git init -b main +git add . +git commit -m "init" +``` + +**(3) VS Code로 폴더 열기**: **File → Open Folder…** → `/home/coder/projects/myapp` → OK +왼쪽에 `myapp` 파일 목록이 보이면 완료. 새 터미널은 이 폴더에서 시작됩니다. + +**(4) 라이브러리 설치**: +```bash +npm install +``` + +> **`.project-env`** 는 이 프로젝트의 설정 파일(DB·S3 접속정보)입니다. 폴더에 들어가면(cd) 자동으로 환경변수에 로드됩니다. +> +> LiteLLM 키만 예외로 워크스페이스 공용 `~/.env`([5번](#5-ai-키-등록-최초-1회))에서 관리합니다. + +## 7. 개발 + +- **편집**: 왼쪽 파일 목록에서 파일 선택 → 수정 → Ctrl+S 저장 +- **AI 도구**: 프로젝트 폴더 안 터미널에서 `claude` 또는 `codex` 실행. 폴더 밖에서 실행하면 프로젝트 파일을 읽지 못합니다. +- **커밋**: 기능 단위로 수시로 커밋합니다. push는 배포 단계에서. + ```bash + git add . && git commit -m "메시지" + ``` +- **DB 접속**: + ```bash + psql "$DATABASE_URL" # 프로젝트 폴더에서 실행 (.project-env 로드 필요) + ``` +- 코드에서는 `process.env.DATABASE_URL`, `process.env.S3_*` 를 사용합니다. +- **`CLAUDE.md`**: 프로젝트 규칙·주의사항을 적어두면 Claude Code가 자동으로 읽고 따릅니다. 예제에 기본 파일이 포함되어 있습니다. +- AI에게는 구체적으로 지시합니다. 예: "로그인 API 만들어줘" 대신 "`src/`에 POST /login 추가, 검증 실패 시 401 반환". 생성된 코드는 [8번](#8-로컬-실행확인)으로 직접 확인 후 커밋합니다. + +### 7-1. bkit 플러그인 (선택) + +Claude Code에 계획→설계→구현→검증 절차를 더하는 플러그인. 터미널의 `claude` CLI에서만 동작합니다(VS Code 확장 미지원). + +설치(최초 1회, `claude` 실행 후 프롬프트에 입력): +``` +/plugin marketplace add popup-studio-ai/bkit-claude-code +/plugin install bkit +``` + +사용: `/pdca pm <기능이름>` — 기능 하나를 계획부터 검증까지 진행. 세분화 명령은 `/pdca plan` `/pdca design` `/pdca do` `/pdca analyze`. + +## 8. 로컬 실행·확인 + +**(1) 실행** +```bash +cd ~/projects/myapp +npm run dev # 저장 시 자동 재시작 +``` +`listening on :3000` 이 에러 없이 출력되면 기동 성공. +실패 시 순서대로 확인: ① `npm install` 했는지 ② 코드 문법 오류 ③ 프로젝트 폴더 밖에서 실행(`.project-env` 미로딩). + +**(2) 연결 점검** — 앱을 띄우지 않고 DB·S3 연결만 확인: +```bash +npm run db:check # "DB OK: ..." 이면 정상 +npm run minio:check # "S3 OK: ..." 이면 정상 +``` +FAIL이면 `.project-env` 값을 확인합니다. 여기서 통과하면 배포 환경에서도 동일하게 동작합니다. + +**(3) 브라우저 미리보기** — 워크스페이스는 클러스터 내부라 `localhost:3000`이 PC 브라우저에서 열리지 않습니다. 포트 포워딩을 사용합니다: +1. VS Code 하단 **PORTS** 탭 → **Forward a Port** → `3000` 입력 +2. 포워딩된 포트의 **Open in Browser** 클릭 → `https://<자동생성>.coder.bokdev.in` + +![브라우저 미리보기](images/coder-ports-preview.png) + +**(4) 엔드포인트 확인** +```bash +curl 127.0.0.1:3000/healthz # {"ok":true} 앱 기동 +curl 127.0.0.1:3000/db # {"ok":true,"now":...} DB 연결 +curl 127.0.0.1:3000/s3 # {"ok":true,"bucket":...} S3 연결 +``` +`"ok": false` 이면 함께 출력되는 `error` 메시지가 원인입니다. + +미리보기 URL은 본인 전용이며 워크스페이스를 끄면 사라집니다. 정식 배포는 [9번](#9-배포-gitea--kubero). + +## 9. 배포 (Gitea + Kubero) + +배포 단위: Gitea `playground` 조직의 레포 1개 = Kubero 앱 1개. +배포 주소: `https://<레포명>.playground.bokdev.in` + +### 9-1. Gitea 원격 레포 생성 (앱당 1회) + +1. https://gitea.bokdev.in → 우측 상단 **`+` → New Repository** +2. **Owner: `playground`** 로 변경, Repository Name 입력 (예: `myapp`) +3. README / .gitignore / License 는 체크하지 않음(빈 저장소여야 함) → **Create Repository** + +### 9-2. push + +```bash +cd ~/projects/myapp +git remote add origin https://gitea.bokdev.in/playground/myapp.git +git push -u origin main +``` +- 최초 push 시 Gitea 승인 화면이 뜨면 **Authorize** 클릭([2번](#2-워크스페이스-만들기-최초-1회)에서 승인했다면 생략됨). +- 이후 수정 반영: `git add . && git commit -m "..." && git push` + +### 9-3. Kubero에 앱 추가 (앱당 1회) + +`ai-dev` pipeline을 사용하시면 되며, 사용자는 그 안에 본인 앱만 추가합니다. + +1. https://kubero.bokdev.in 접속 +2. **`ai-dev`** 파이프라인 선택 +3. **Production** phase에서 **Create App**: + - Name: 레포명과 동일하게 입력 + - Repository: `https://gitea.bokdev.in/playground/<레포명>.git` + - Branch: `main`, Port: `3000` + +4. 생성하면 빌드·배포가 실행됩니다. + +> 자동 빌드는 현재 미연동입니다. **코드 수정 후에는 push 하고 Kubero에서 해당 앱의 빌드를 다시 실행합니다.** + +### 9-4. 확인 + +배포·재시작 직후 약 1~2분은 초기화(코드 다운로드·설치) 시간입니다. 404가 나와도 기다린 뒤 다시 확인합니다. + +```bash +curl https://<레포명>.playground.bokdev.in/healthz # {"ok":true} +curl https://<레포명>.playground.bokdev.in/db +curl https://<레포명>.playground.bokdev.in/s3 +``` + +![배포된 앱](images/08-deployed-app.png) + +문제가 있으면 Kubero에서 해당 앱의 빌드/배포 로그를 확인합니다. 로그에 `listening on :3000` 이 보이면 기동 성공입니다. + +## 10. Coder Workspace 켜고 끄기 + +- Coder workspace 재기동이 필요한 경우: Coder 워크스페이스 화면에서 **Stop** +- 다시 사용: **Start** (VS Code Web 아이콘이 뜰 때까지 대기) +- `~/projects` 만 보존됩니다. 그 외 경로의 파일은 사라질 수 있습니다. + +## 문제 해결 + +- **로그인을 서비스마다 해야 하나요** → 아니요. 사번 계정 SSO 하나로 전부 로그인됩니다. +- **파일이 사라졌어요** → `~/projects` 밖에 저장한 경우 파일이 유실될 수 있습니다([3번](#3-vs-code-열기)). +- **AI 도구 401 오류** → `update-litellm-key` 재실행([5번](#5-ai-키-등록-최초-1회)). 키가 `sk-`로 시작하는지 확인. +- **AI 도구 400 (Invalid model)** → [5번](#5-ai-키-등록-최초-1회) 표의 기본 모델명 사용. +- **키 등록 후 VS Code가 먹통** → VS Code 서버 Stop → Start([5번](#5-ai-키-등록-최초-1회)). +- **`$DATABASE_URL` 이 비어 있음** → 프로젝트 폴더 안에서 실행해야 `.project-env` 가 로드됩니다([6번](#6-새-프로젝트-시작)). +- **`npm run dev` 가 `Cannot find package ...`** → `npm install` 미실행([6번](#6-새-프로젝트-시작)). +- **push 인증을 물어봄** → Gitea 승인을 아직 안 한 경우. 승인 화면에서 Authorize([9-2](#9-2-push)). +- **다른 계정으로 push/연동됨** → 브라우저에 남아 있던 Gitea 로그인 세션 때문입니다. Gitea 로그아웃 후 재승인하거나 시크릿 창 사용([2번](#2-워크스페이스-만들기-최초-1회)). +- **배포 주소가 404** → ① 배포 직후 1~2분 대기 ② `/healthz` 확인 ③ Kubero 로그 확인([9-4](#9-4-확인)). +- **`/healthz` 는 되는데 `/db`·`/s3` 가 500** → 먼저 로컬에서 `npm run db:check` / `minio:check` 통과 확인([8번](#8-로컬-실행확인)). 로컬에서 되면 Kubero 로그의 에러 메시지 확인. +- **배포가 옛날 코드** → push 됐는지 확인 후 Kubero에서 빌드 재실행([9-3](#9-3-kubero에-앱-추가-앱당-1회)). +- **DB가 비어 있음** → 정상입니다. 빈 전용 스키마가 제공되며 테이블은 직접 생성합니다. +- **K8s에 직접 접근하고 싶어요** → 직원은 K8s에 직접 접근하지 않습니다. Coder·Gitea·Kubero로 개발·배포가 완결됩니다. + +--- + +문의: 인프라 담당자 \ No newline at end of file diff --git a/USER-MANUAL.md b/USER-MANUAL.md deleted file mode 100644 index 62a73f0..0000000 --- a/USER-MANUAL.md +++ /dev/null @@ -1,482 +0,0 @@ -# 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 | 업로드된 파일 확인 (선택) | 별도 로그인(관리자 안내) | - - -| **개발 중 앱 미리보기** | `https://<자동생성>.coder.bokdev.in` | 워크스페이스에서 실행한 앱 (10번) | 본인 전용 | -| **배포된 앱 주소** | `https://<앱이름>.playground.bokdev.in` | 실제 서비스 (13번) | 공개 | - -> 코드에서 쓰는 연결정보(DB 비밀번호·S3 키 등)는 **자동으로 주입**됩니다. 직접 외울 필요 없습니다. -> (개발할 땐 `.project-env` 파일에, 배포할 땐 포털이 자동으로 넣어 줍니다.) - -> 🔑 **로그인 정리**: 포털 로그인만으로 자동으로 열리는 건 **Coder·Gitea** 입니다. **Kubero** 는 클릭하면 로그인 화면이 한 번 더 나올 수 있으며 **같은 사번 계정**으로 로그인하면 됩니다. **OpenEverest·MinIO** 는 별도 계정이 필요하니 접근이 막히면 인프라 담당자에게 문의하세요. - ---- - -## 1. 포털(Backstage) 로그인 - -1. 브라우저에서 **https://backstage.bokdev.in** 접속합니다. -2. 로그인 화면에서 **사번 계정**으로 로그인합니다. - - **아이디** = 본인 사번 (예: `2620227`) - - **비밀번호** = 본인 비밀번호 (초기 비밀번호를 받았다면 첫 로그인 후 변경 권장) -3. 로그인은 회사 통합 인증(SSO)으로 처리됩니다. **여기서 한 번 로그인하면 Coder·Gitea 는 다시 로그인 없이 자동으로 열립니다.** Kubero 등 그 밖의 도구는 클릭 후 로그인 화면이 한 번 더 나올 수 있습니다(Kubero 는 같은 사번 계정으로 로그인). - -![포털 로그인 화면](images/01-login.png) - -> 💡 **비밀번호 변경**: 로그인 화면(또는 계정 메뉴)의 "비밀번호 변경" 링크에서 바꿀 수 있습니다. - ---- - -## 2. 홈 대시보드 둘러보기 - -로그인하면 **홈(카드 대시보드)** 이 나옵니다. 자주 쓰는 도구로 바로 가는 카드들이 있습니다. **Coder·Gitea 카드는 `SSO 자동로그인` 이라 클릭하면 바로 들어가고,** 그 밖의 카드(Kubero·OpenEverest·MinIO 등)는 클릭 후 한 번 더 로그인이 필요할 수 있습니다(Kubero 는 같은 사번 계정). - -| 카드 | 한 줄 설명 | -|---|---| -| **Coder** | 코딩하는 곳(웹 VS Code). 실제 개발은 여기서 | -| **Gitea** | 코드 저장소(Git). 내 앱 코드가 보관되는 곳 | -| **Kubero** | 배포 플랫폼. 앱이 실제로 실행/공개되는 곳 | -| **OpenEverest** | 데이터베이스 관리 화면. **MongoDB·MySQL·PostgreSQL** 을 들어가서 `create database` 로 직접 만들 수 있음 | -| **MinIO** | 파일/이미지 저장소(S3) | -| **LiteLLM / Chat** | AI 모델 게이트웨이 / AI 채팅 | -| **Harbor** | 컨테이너 이미지 저장소(직접 쓸 일은 거의 없음) | - -![홈 카드 대시보드](images/02-home-dashboard.png) - -- 왼쪽 사이드바: **Home**(이 화면) / **Catalog**(등록된 앱 목록) / **Create**(앱 만들기) -- 내가 만든 앱들은 **Catalog**(`/catalog`)에서 모아 볼 수 있습니다. - -> 처음이라면 먼저 **4번(워크스페이스 만들기)** 으로 개발 환경을 준비한 뒤 **3번(앱 만들기)** 으로 와도 되고, -> 순서대로 3번부터 진행해도 됩니다. 추천 순서는 위 흐름도(맨 위)를 참고하세요. - ---- - -## 3. 포털에서 앱 만들기 ("AI DEV 앱 만들기") - -새 앱을 시작하는 **표준 방법**입니다. 이 한 번으로 **저장소(Gitea) 생성 + 샘플 코드 채우기 + 포털 등록**이 자동으로 됩니다. -(예전처럼 Gitea에서 직접 저장소를 만들 필요가 없습니다.) - -### 3-1. 템플릿 실행 - -1. 포털 사이드바에서 **Create**(또는 상단 **Create...**) 클릭. -2. **"AI DEV 앱 만들기"** 템플릿의 **CHOOSE** 클릭. - -![템플릿 선택](images/03-template-choose.png) - -### 3-2. 4단계 입력 (Next 버튼으로 진행) - -**1단계 · 앱 기본 정보** - -| 항목 | 설명 | -|---|---| -| **앱 이름** | 소문자/숫자/하이픈만. 예: `to-do`, `my-api` (최대 30자). 이 이름이 곧 **저장소 이름·배포 주소**가 됩니다. 남과 겹치지 않게 정하세요. | -| **한 줄 설명** | 저장소 설명에 들어갈 짧은 글 (필수) | - -![1단계 기본 정보](images/04-step1-basic.png) - -**2단계 · 소유자** -- 이 앱을 소유할 팀/사용자. 기본값(`playground`)을 그대로 두면 됩니다. (본인으로 바꿔도 됩니다.) - -**3단계 · 연결정보 & 테스트** -- 앱에서 쓸 **데이터베이스(DB)** 와 **파일저장소(S3)** 사용 여부를 체크합니다. -- **"연결 테스트"** 버튼으로 본인 연결정보가 잘 붙는지 미리 확인할 수 있습니다. -- ⚠️ 사용자·비밀번호·키는 **배포 시 사번 기준으로 자동 주입**되며 **코드(저장소)에는 저장되지 않습니다.** 안심하세요. - -![3단계 연결정보 테스트](images/05-step3-connection.png) - -**4단계 · 배포 옵션** -- **생성 직후 Kubero 로 배포** : - - ✅ **켜기(처음엔 이걸 추천)** — 만들자마자 배포되고 **자동배포 파이프라인이 설정**됩니다. 이후 코드를 push 할 때마다 **자동으로 다시 배포**돼서 가장 편합니다. - - ⬜ **끄기** — 저장소만 먼저 만들고, 개발이 끝난 뒤 배포하고 싶을 때. - -> 💡 **처음엔 켜기를 추천**합니다. 빈 앱(샘플)이 먼저 배포되면서 배포 통로가 자동으로 뚫립니다. 그 다음부터는 Coder에서 개발 → `git push` 만 하면 알아서 재배포됩니다. - -### 3-3. 생성 - -- **Review** 화면에서 값을 확인하고 **CREATE** 를 누릅니다. -- 진행 로그가 단계별로 흐릅니다(샘플 코드 가져오기 → 메타 생성 → Gitea 게시 → 카탈로그 등록 → (선택)배포). -- 끝나면 **Gitea 저장소 링크**와 **카탈로그 항목 링크**가 나옵니다. 이제 코드의 출발점이 준비됐습니다. - -![생성 완료](images/06-create-done.png) - -> 만든 앱 이름을 기억해 두세요. 다음 단계(8번 `open-project <앱이름>`)에서 씁니다. - ---- - -# 〔개발 환경 준비 — 처음 한 번만〕 - -## 4. Coder 워크스페이스 만들기 (최초 1회) - -워크스페이스 = 본인 전용 개발용 컨테이너(VS Code + 각종 도구가 깔린 가상 PC). - -1. 홈에서 **Coder** 카드 클릭(자동 로그인) → **Workspaces** 화면. -2. **`Create Workspace`** 클릭 → 템플릿 **`aidev-k8s`** 선택. -3. 설정값 입력 - - **Name**: 워크스페이스 이름 (예: `ws-<사번>` 또는 자유롭게) - - **CPU / Memory / Home disk**: 기본값(2 Core / 4 GiB / 10 GiB)이면 충분합니다. 나중에 늘릴 수 있습니다. - - *(선택) Gitea 계정 연동*: `External Authentication` 항목의 **승인**을 미리 눌러도 되고, 나중에(7번) 해도 됩니다. - - ![Gitea 계정 연동](images/coder-gitea-auth.png) - -4. **`Create Workspace`** 클릭 → 빌드 시작. - - **처음엔 이미지 다운로드로 2~5분** 걸릴 수 있습니다. **VS Code Web 아이콘이 보일 때까지** 기다리세요. - - 상태가 **Running** 이면 준비 완료. - -> 워크스페이스는 한 번 만들면 계속 재사용합니다. 다음부터는 **Start** 만 누르면 됩니다. - ---- - -## 5. VS Code 열기 - -1. 워크스페이스 화면에서 **`VS Code Web`** 버튼 클릭. -2. 브라우저에 VS Code가 열리고, 자동으로 **`/home/coder/projects`** 폴더가 열립니다. ("Yes, I trust the authors" 클릭) -3. 그 안에 **`sample`** 폴더가 있습니다 — 참조용 예제이니 **직접 고치지 말고** 보기만 하세요. - -> 작업 파일은 반드시 **`/home/coder/projects`** 아래에 두세요. **이 폴더만 영구 보존**됩니다. -> (워크스페이스를 stop/재시작해도 유지. 그 밖의 위치는 사라질 수 있습니다.) - ---- - -## 6. AI 에이전트 사용 설정 (최초 1회) — LiteLLM 키 입력 - -Claude Code / Codex / Gemini 가 사내 AI 게이트웨이를 쓰려면 **본인 LiteLLM 키**가 필요합니다. -키는 **한 곳에만** 넣으면 모든 도구가 공유합니다. - -1. 터미널 열기: VS Code 상단 메뉴(작대기 3개) **Terminal → New Terminal** (화면 아래에 터미널 창이 뜸). -2. 다음을 입력하고, 안내가 나오면 발급받은 본인 키(`sk-...`)를 붙여넣습니다: - ```bash - update-litellm-key - ``` - ``` - LiteLLM virtual key 입력 (sk-...): sk-여기에-본인-키-붙여넣기 - 키 갱신 완료. 현재 터미널에 즉시 적용됨. - ``` - > 이 명령은 키를 저장하고 **현재 터미널에 바로 적용**합니다. 새 터미널을 열거나 `source` 할 필요 없습니다. 키를 바꿀 때도 같은 명령을 다시 쓰면 됩니다. -3. 확인: - ```bash - echo $ANTHROPIC_BASE_URL # https://litellm.bok.or.kr 가 나오면 정상 - claude # Claude Code 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` | - -> 키는 본인 워크스페이스 안에만 저장되고, 코드/깃에는 올라가지 않습니다. 게이트웨이 주소는 이미 설정돼 있으니 건드릴 필요 없습니다. - ---- - -## 7. Git(Gitea) 사용 — 최초 1회 승인 - -코드 저장소는 사내 **Gitea**(https://gitea.bokdev.in)입니다. 토큰 입력 없이 자동 인증됩니다. - -1. 터미널에서 처음 `git clone`/`git push`(또는 8번 `open-project`)를 하면 **Gitea 승인 화면**으로 안내됩니다. - - 또는 Coder 화면의 **`Gitea`** external auth 항목에서 **Authorize** 를 미리 눌러도 됩니다. -2. 한 번 **Authorize(승인)** 하면, 이후로는 비밀번호 입력 없이 clone/push 가 됩니다. - ---- - -# 〔앱마다 반복하는 개발·배포 흐름〕 - -## 8. 내 앱 가져오기 (open-project) - -3번 포털에서 만든 앱을 워크스페이스로 가져옵니다. **터미널에 한 줄이면 됩니다.** -(`<앱이름>` 은 3번에서 정한 이름) - -```bash -open-project <앱이름> -``` - -이 명령이 자동으로: -- 포털이 만든 Gitea 저장소를 **clone** 하고, -- 그 폴더에 **`.project-env`**(본인 DB/S3 접속정보)를 **자동 생성**합니다(이미 있으면 보존). -- 이미 받아둔 경우엔 `git pull` 로 최신화합니다. - -끝나면 이렇게 안내가 나옵니다: -``` -준비 완료: /home/coder/projects/<앱이름> — 'cd <앱이름> && npm install && npm run dev' 로 시작하세요. -``` - -**그 다음, VS Code로 그 폴더 열기** (왼쪽 파일 목록에 보이게): -- 상단 메뉴 **File → Open Folder…** → 경로칸에 **`/home/coder/projects/<앱이름>`** 입력 → **OK** -- 창이 새로고침되며 왼쪽에 파일들이 보이면 성공입니다. (이제 새 터미널은 자동으로 이 폴더에서 시작됩니다.) - -**필요한 라이브러리 설치** (처음 1회): -```bash -cd ~/projects/<앱이름> -npm install # 안 하면 실행이 실패합니다 -``` - -> **`.project-env` 가 그 프로젝트의 설정 파일**(DB·S3)입니다. 폴더에 들어가면(`cd`) 자동으로 환경변수에 반영됩니다. -> 이 파일은 **git에 올라가지 않습니다**(자격증명 보호 — 정상). LiteLLM 키만은 워크스페이스 공용이라 `~/.env`(6번)에서 관리합니다. - ---- - -## 9. 개발하기 - -(8번에서 **본인 프로젝트 폴더를 Open Folder 해 둔 상태**에서) - -- **코드 편집**: 왼쪽 파일 목록에서 파일(예: `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` 에 이미 들어 있습니다. - -### 9-1. AI 도구를 잘 쓰는 법 (팁) - -- **항상 프로젝트 폴더 안에서 실행**하세요. AI는 "지금 폴더"의 파일을 읽어 맥락을 잡습니다. -- **`CLAUDE.md` 를 활용**하세요. 샘플에는 프로젝트 규칙(컨테이너 개발, 배포 방식, 비밀값 금지 등)을 적은 `CLAUDE.md`가 들어 있고, AI가 자동으로 읽습니다. 규칙·주의사항을 여기에 적어두면 그대로 따릅니다. -- **구체적으로 시키세요**: "로그인 API 만들어줘" 보다 "`src/` 에 POST /login 엔드포인트 추가, 입력 검증 후 실패 시 401 반환" 처럼. -- **확인은 직접**: AI가 만든 코드도 10번(로컬 실행)·11번(컨테이너)으로 **반드시 본인이 동작 확인** 후 커밋하세요. -- 키가 안 먹으면(401) → 6번 재실행. 모델 오류(400)면 → 6번 표의 모델명. - -### 9-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이 알맞은 흐름을 골라 줍니다. - ---- - -## 10. 로컬에서 실행하고 브라우저로 확인하기 - -코드를 바로 실행해 동작을 확인하는 단계입니다(가장 빠름). - -> **배포 전, 점점 "실제 배포에 가깝게" 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번입니다. - ---- - -## 11. 컨테이너로 빌드해서 확인하기 (podman) - -10번은 코드를 그냥 실행한 것이고, 실제 배포는 **컨테이너 이미지**로 띄웁니다. -배포 전에 **같은 방식(컨테이너)으로 한 번 돌려보면** 배포 후 문제를 미리 잡을 수 있습니다. (선택이지만 권장) - -**1) 빌드** — 프로젝트에 `Dockerfile` 이 있으면: -```bash -cd ~/projects/<앱이름> -podman build -t <앱이름> . # 현재 폴더의 Dockerfile 로 이미지 빌드 -``` -(`docker build ...` 도 동일하게 동작합니다 — 런타임이 podman 일 뿐입니다.) - -마지막에 `Successfully tagged localhost/<앱이름>:latest` 가 보이면 **빌드 성공**. -- **실패하면** 빨간 `Error:` 줄과 **몇 번째 STEP 에서 멈췄는지** 보세요. 가장 흔한 건 `npm install` 단계 실패(의존성 문제, `package.json` 확인). - -**2) 실행** -```bash -podman run --rm -p 3000:3000 --env-file .project-env <앱이름> -``` -- `--env-file .project-env` 로 DB/S3 값을 컨테이너에 넣어줍니다(없으면 `/db`·`/s3` 가 실패). -- 기동되면 10번처럼 `listening on :3000` 이 보입니다. - -**3) 동작 확인** — 접속은 **`127.0.0.1`** 로 (가끔 `localhost` 가 안 잡힘). 기대 응답은 10번 표와 동일: -```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":...} -``` -- 브라우저로 보려면 10번처럼 **PORTS → Forward 3000 → Open in Browser**. -- 끝나면 터미널에서 **Ctrl+C** 로 멈춥니다(`--rm` 이라 자동 삭제). 안 멈추면 `podman ps` → `podman stop `. - -> 여기서 **빌드 성공 + 3개 엔드포인트 모두 `ok:true`** 면 배포도 거의 그대로 됩니다. - ---- - -## 12. Git(Gitea)에 올리기 - -`open-project` 로 받은 폴더는 **이미 Gitea 저장소에 연결돼 있습니다**(3번 포털이 만들어 줬으므로). 따로 저장소를 만들 필요 없이 **수정 → 커밋 → push** 만 하면 됩니다. - -```bash -cd ~/projects/<앱이름> -git add . -git commit -m "기능 구현" -git push -``` - -- 인증은 자동입니다(7번 Gitea 승인을 한 번 했다면). 처음이면 승인 화면이 한 번 뜹니다. -- 이후로는 위 3줄만 반복하면 됩니다. - -> **`.project-env` 는 git에 안 올라갑니다**(자격증명 보호 — 정상). `git status` 에 안 보여도 맞습니다. -> 배포 환경의 DB/S3 값은 **포털이 자동으로 넣어주므로** 따로 등록할 필요가 없습니다(13번). - ---- - -## 13. 배포하고 확인하기 (Kubero) - -배포는 **Kubero**가 담당합니다. 좋은 소식: 3번에서 **"생성 직후 Kubero 로 배포"를 켰다면 배포 통로가 이미 자동으로 설정**돼 있습니다. 그래서 개발자가 할 일은 사실상 **`git push`(12번)** 뿐입니다. - -### 자동 배포 (3번에서 deployNow 를 켠 경우 — 추천 흐름) - -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번 로컬에서 먼저 통과했는지. - ---- - -## 14. 워크스페이스 켜고 끄기 - -- **그만 쓸 때**: Coder 워크스페이스 화면 → **Stop** (자원 절약. `~/projects` 파일은 보존). -- **다시 쓸 때**: **Start** (수십 초 내 기동). -- **업데이트 안내(`Update` 버튼)** 가 뜨면 눌러서 최신 환경으로 갱신하세요. `~/projects` 파일은 유지됩니다. - ---- - -## 자주 묻는 것 - -- **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로 충분합니다. - ---- - -문의: 인프라 담당자