AI DEV 개발·배포 매뉴얼 (개발자용)

행번 계정 하나로 Coder에서 개발하고, Gitea에 push, Kubero로 배포합니다. DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM - key 제외)는 워크스페이스에 미리 연결되어 있습니다.

목차

최초 1회 1. 로그인 → 2. 워크스페이스 만들기 → 3. VS Code 열기 → 5. AI 키 등록

앱마다 6. 새 프로젝트 시작 → 7. 개발 → 8. 로컬 실행·확인 → 9. 배포

[최초 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)
   • 비밀번호: 본인 비밀번호 (초기 비밀번호: bok1234!! + 행번 7자리)

3. 이후 Coder·Gitea·Kubero는 추가 로그인 없이 같은 계정으로 열립니다.

   • Kubero의 경우 OAuth로 로그인하기를 눌러 SSO 로그인이 가능합니다.

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

Coder 워크스페이스 = 본인 전용 개발 컨테이너(VS Code + 개발 도구 일체).

⚠️주의: 같은 브라우저에 다른 계정으로 Gitea 로그인이 남아 있으면 그 계정으로 연동됩니다.
승인 전에 Gitea에서 로그아웃했는지 확인하거나, 시크릿 모드에서 진행합니다.
Coder와 Gitea의 로그인 계정이 일치하지 않는 경우 Workspace 생성 후 계정 불일치로 Push가 되지 않을 수 있습니다.

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) 사용. 추후 변경 가능.

   

3. Create Workspace 클릭

4. 최초 빌드는 2~5분 소요. 상태가 Running이 되면 완료.

주의: 워크스페이스는 한 번 만들면 계속 사용합니다.

3. VS Code 열기

1. 워크스페이스 화면에서 VS Code Web 아이콘 클릭
2. /home/coder/projects 폴더가 자동으로 열립니다. ("Yes, I trust the authors" 클릭)
3. 안에 sample 폴더가 있습니다. DB·S3 연결이 확인된 참조용 예제이며 직접 수정하지 않습니다. 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회)

Claude Code / Codex 는 사내 AI 게이트웨이(LiteLLM)를 사용합니다. 발급받은 본인 virtual key를 한 번만 등록하면 CLI·확장이 모두 공유합니다.

1. 터미널 열기: VS Code 메뉴(좌상단 ☰) → Terminal → New Terminal
2. 아래 명령 실행 후 본인 키(sk-...) 입력:

   update-litellm-key
   

   LiteLLM virtual key 입력 (sk-...): sk-본인-키
   키 갱신 완료 (len=25). 현재 터미널에 즉시 적용됨.
   

3. 확인:

   echo $ANTHROPIC_BASE_URL   # https://litellm.bok.or.kr 이면 정상
   claude
   

   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 에서 실행:

cd ~/projects
cd sample && git pull && cd ..   # 예제 최신화
new-project myapp                # 예제를 ~/projects/myapp 으로 복사 + .project-env 자동 생성

myapp은 예시입니다. 이 이름은 Gitea 레포명으로 설정할 이름과 동일하게 맞추시면 되고, 소문자·숫자·하이픈만 사용합니다.

(2) git 초기화 — 개발 시작 시점에 합니다. 커밋 이력을 처음부터 관리하기 위함이며, 원격(Gitea) 연결은 배포 단계(9번)에서 합니다:

cd ~/projects/myapp
git init -b main
git add .
git commit -m "init project"

(3) VS Code로 폴더 열기: File → Open Folder… → /home/coder/projects/myapp → OK 왼쪽에 myapp 파일 목록이 보이면 완료. 새 터미널은 이 폴더에서 시작됩니다.

(4) 라이브러리 설치:

npm install

.project-env 는 이 프로젝트의 설정 파일(DB·S3 접속정보)입니다. 폴더에 들어가면(cd) 자동으로 환경변수에 로드됩니다.

LiteLLM 키만 예외로 워크스페이스 공용 ~/.env(5번)에서 관리합니다.

7. 개발

• 편집: 왼쪽 파일 목록에서 파일 선택 → 수정 → Ctrl+S 저장
• AI 도구: 프로젝트 폴더 안 터미널에서 claude 또는 codex 실행. 폴더 밖에서 실행하면 프로젝트 파일을 읽지 못합니다.
• 커밋: 기능 단위로 수시로 커밋합니다. push는 배포 단계에서.

  git add . && git commit -m "메시지"
  

• DB 접속:

  psql "$DATABASE_URL"        # 프로젝트 폴더에서 실행 (.project-env 로드 필요)
  

• 코드에서는 process.env.DATABASE_URL, process.env.S3_* 를 사용합니다.
• CLAUDE.md: 프로젝트 규칙·주의사항을 적어두면 Claude Code가 자동으로 읽고 따릅니다. 예제에 기본 파일이 포함되어 있습니다.
• AI에게는 구체적으로 지시합니다. 예: "로그인 API 만들어줘" 대신 "src/에 POST /login 추가, 검증 실패 시 401 반환". 생성된 코드는 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) 실행

cd ~/projects/myapp
npm run dev             # 저장 시 자동 재시작

listening on :3000 이 에러 없이 출력되면 기동 성공. 실패 시 순서대로 확인: ① npm install 했는지 ② 코드 문법 오류 ③ 프로젝트 폴더 밖에서 실행(.project-env 미로딩).

(2) 연결 점검 — 앱을 띄우지 않고 DB·S3 연결만 확인:

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

(4) 엔드포인트 확인

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)

배포 단위: Gitea playground 조직의 레포 1개 = Kubero 앱 1개. 배포 주소: https://<레포명>.playground.bokdev.in

9-1. Gitea 원격 레포 생성 (앱당 1회)

1. https://gitea.bokdev.in/playground → 우측 상단 + → New Repository
   
2. Owner: playground 로 변경, Repository Name 입력 (예: myapp)
3. README / .gitignore / License 는 체크하지 않음(빈 저장소여야 함) → Create Repository

9-2. push

cd ~/projects/myapp
git remote add origin https://gitea.bokdev.in/playground/myapp.git
git push -u origin main

• 최초 push 시 Gitea 승인 화면이 뜨면 Authorize 클릭(2번에서 승인했다면 생략됨).
• 이후 수정 반영: git add . && git commit -m "..." && git push

9-3. Kubero에 앱 추가 (앱당 1회)

TODO: Kubero 배포 오류 수정 필요

ai-dev pipeline을 사용하시면 되며, 사용자는 그 안에 본인 앱만 추가합니다.

1. https://kubero.bokdev.in 접속
2. playground 파이프라인 선택
3. Production 아래의 + 버튼을 클릭해 앱을 추가
4. App Name과 환경 ENVIRONMENT VARIABLES 추가
   • .project-env 파일을 업로드 하면 자동으로 파싱되어 등록됩니다.

자동 빌드는 현재 미연동입니다. 코드 수정 후에는 push 하고 Kubero에서 해당 앱의 빌드를 다시 실행합니다.

9-4. 확인

배포·재시작 직후 약 1~2분은 초기화(코드 다운로드·설치) 시간입니다. 일시적으로 404가 나오는 경우, 잠시 기다린 후 Ctrl + Shift + R로 강력 새로고침 후 확인해주세요.

curl https://<레포명>.playground.bokdev.in/healthz   # {"ok":true}
curl https://<레포명>.playground.bokdev.in/db
curl https://<레포명>.playground.bokdev.in/s3

문제가 있으면 Kubero에서 해당 앱의 빌드/배포 로그를 확인합니다. 로그에 listening on :3000 이 보이면 기동 성공입니다.

FAQ

• Coder Workspace 켜고 끄기

  • Coder workspace 재기동이 필요한 경우: Coder 워크스페이스 화면에서 Stop
  • 다시 사용: Start (VS Code Web 아이콘이 뜰 때까지 대기)
  • ~/projects 만 보존됩니다. 그 외 경로의 파일은 사라질 수 있습니다.

• 로그인을 서비스마다 해야 하나요 → 아니요. 행번 계정 SSO 하나로 전부 로그인됩니다.

• Coder에서 파일이 사라졌어요 → ~/projects 밖에 저장한 경우 파일이 유실될 수 있습니다(3번).

• AI 도구 401 오류 → update-litellm-key 재실행(5번). 키가 sk-로 시작하는지 확인.

• AI 도구 400 (Invalid model) → 5번 표의 기본 모델명 사용.

• 키 등록 후 VS Code가 먹통 → VS Code 서버 Stop → Start(5번).

• $DATABASE_URL 이 비어 있음 → 프로젝트 폴더 안에서 실행해야 .project-env 가 로드됩니다(6번).

• npm run dev 가 Cannot find package ... → npm install 미실행(6번).

• push 인증을 물어봄 → Gitea 승인을 아직 안 한 경우. 승인 화면에서 Authorize(9-2).

• 다른 계정으로 push/연동됨 → 브라우저에 남아 있던 Gitea 로그인 세션 때문입니다. Gitea 로그아웃 후 재승인하거나 시크릿 창 사용(2번).

• 배포 주소가 404 → ① 배포 직후 1~2분 대기 ② /healthz 확인 ③ Kubero 로그 확인(9-4).

• /healthz 는 되는데 /db·/s3 가 500 → 먼저 로컬에서 npm run db:check / minio:check 통과 확인(8번). 로컬에서 되면 Kubero 로그의 에러 메시지 확인.

• 배포가 옛날 코드 → push 됐는지 확인 후 Kubero에서 빌드 재실행(9-3).

• DB가 비어 있음 → 정상입니다. 빈 전용 스키마가 제공되며 테이블은 직접 생성합니다.

• K8s에 직접 접근하고 싶어요 → 직원은 K8s에 직접 접근하지 않습니다. Coder·Gitea·Kubero로 개발·배포가 완결됩니다.

문의

• IT 전략국 클라우드팀 김창록 팀장
• IT 전략국 정보시스템개발팀 박성록 과장
• IT 전략국 클라우드팀 이혜민 조사역