Files

Your Name cdfd274fc9 Add USER-MANUAL.md

2026-06-25 17:56:20 +09:00

29 KiB

Raw Blame History

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

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

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

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

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	업로드된 파일 확인 (선택)	별도 로그인(관리자 안내)

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

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

1. 포털(Backstage) 로그인

브라우저에서 https://backstage.bokdev.in 접속합니다.
로그인 화면에서 사번 계정으로 로그인합니다.
- 아이디 = 본인 사번 (예: 2620227)
- 비밀번호 = 본인 비밀번호 (초기 비밀번호를 받았다면 첫 로그인 후 변경 권장)
로그인은 회사 통합 인증(SSO)으로 처리됩니다. 여기서 한 번 로그인하면 Coder·Gitea 는 다시 로그인 없이 자동으로 열립니다. Kubero 등 그 밖의 도구는 클릭 후 로그인 화면이 한 번 더 나올 수 있습니다(Kubero 는 같은 사번 계정으로 로그인).

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

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	컨테이너 이미지 저장소(직접 쓸 일은 거의 없음)

왼쪽 사이드바: Home(이 화면) / Catalog(등록된 앱 목록) / Create(앱 만들기)
내가 만든 앱들은 Catalog(/catalog)에서 모아 볼 수 있습니다.

처음이라면 먼저 4번(워크스페이스 만들기) 으로 개발 환경을 준비한 뒤 3번(앱 만들기) 으로 와도 되고, 순서대로 3번부터 진행해도 됩니다. 추천 순서는 위 흐름도(맨 위)를 참고하세요.

3. 포털에서 앱 만들기 ("AI DEV 앱 만들기")

새 앱을 시작하는 표준 방법입니다. 이 한 번으로 저장소(Gitea) 생성 + 샘플 코드 채우기 + 포털 등록이 자동으로 됩니다. (예전처럼 Gitea에서 직접 저장소를 만들 필요가 없습니다.)

3-1. 템플릿 실행

포털 사이드바에서 Create(또는 상단 Create...) 클릭.
"AI DEV 앱 만들기" 템플릿의 CHOOSE 클릭.

3-2. 4단계 입력 (Next 버튼으로 진행)

1단계 · 앱 기본 정보

항목	설명
앱 이름	소문자/숫자/하이픈만. 예: `to-do`, `my-api` (최대 30자). 이 이름이 곧 저장소 이름·배포 주소가 됩니다. 남과 겹치지 않게 정하세요.
한 줄 설명	저장소 설명에 들어갈 짧은 글 (필수)

2단계 · 소유자

이 앱을 소유할 팀/사용자. 기본값(playground)을 그대로 두면 됩니다. (본인으로 바꿔도 됩니다.)

3단계 · 연결정보 & 테스트

앱에서 쓸 데이터베이스(DB) 와 파일저장소(S3) 사용 여부를 체크합니다.
"연결 테스트" 버튼으로 본인 연결정보가 잘 붙는지 미리 확인할 수 있습니다.
⚠️ 사용자·비밀번호·키는 배포 시 사번 기준으로 자동 주입되며 코드(저장소)에는 저장되지 않습니다. 안심하세요.

4단계 · 배포 옵션

생성 직후 Kubero 로 배포 :
- ✅ 켜기(처음엔 이걸 추천) — 만들자마자 배포되고 자동배포 파이프라인이 설정됩니다. 이후 코드를 push 할 때마다 자동으로 다시 배포돼서 가장 편합니다.
- ⬜ 끄기 — 저장소만 먼저 만들고, 개발이 끝난 뒤 배포하고 싶을 때.

💡 처음엔 켜기를 추천합니다. 빈 앱(샘플)이 먼저 배포되면서 배포 통로가 자동으로 뚫립니다. 그 다음부터는 Coder에서 개발 → git push 만 하면 알아서 재배포됩니다.

3-3. 생성

Review 화면에서 값을 확인하고 CREATE 를 누릅니다.
진행 로그가 단계별로 흐릅니다(샘플 코드 가져오기 → 메타 생성 → Gitea 게시 → 카탈로그 등록 → (선택)배포).
끝나면 Gitea 저장소 링크와 카탈로그 항목 링크가 나옵니다. 이제 코드의 출발점이 준비됐습니다.

만든 앱 이름을 기억해 두세요. 다음 단계(8번 open-project <앱이름>)에서 씁니다.

〔개발 환경 준비 — 처음 한 번만〕

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

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

홈에서 Coder 카드 클릭(자동 로그인) → Workspaces 화면.
Create Workspace 클릭 → 템플릿 aidev-k8s 선택.
설정값 입력
- Name: 워크스페이스 이름 (예: ws-<사번> 또는 자유롭게)
- CPU / Memory / Home disk: 기본값(2 Core / 4 GiB / 10 GiB)이면 충분합니다. 나중에 늘릴 수 있습니다.
- (선택) Gitea 계정 연동: External Authentication 항목의 승인을 미리 눌러도 되고, 나중에(7번) 해도 됩니다.
Create Workspace 클릭 → 빌드 시작.
- 처음엔 이미지 다운로드로 2~5분 걸릴 수 있습니다. VS Code Web 아이콘이 보일 때까지 기다리세요.
- 상태가 Running 이면 준비 완료.

워크스페이스는 한 번 만들면 계속 재사용합니다. 다음부터는 Start 만 누르면 됩니다.

5. VS Code 열기

워크스페이스 화면에서 VS Code Web 버튼 클릭.
브라우저에 VS Code가 열리고, 자동으로 /home/coder/projects 폴더가 열립니다. ("Yes, I trust the authors" 클릭)
그 안에 sample 폴더가 있습니다 — 참조용 예제이니 직접 고치지 말고 보기만 하세요.

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

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

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

터미널 열기: VS Code 상단 메뉴(작대기 3개) Terminal → New Terminal (화면 아래에 터미널 창이 뜸).
다음을 입력하고, 안내가 나오면 발급받은 본인 키(sk-...)를 붙여넣습니다:
```
update-litellm-key
```
```
LiteLLM virtual key 입력 (sk-...): sk-여기에-본인-키-붙여넣기
키 갱신 완료. 현재 터미널에 즉시 적용됨.
```
이 명령은 키를 저장하고 현재 터미널에 바로 적용합니다. 새 터미널을 열거나 source 할 필요 없습니다. 키를 바꿀 때도 같은 명령을 다시 쓰면 됩니다.

확인:

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)입니다. 토큰 입력 없이 자동 인증됩니다.

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

〔앱마다 반복하는 개발·배포 흐름〕

8. 내 앱 가져오기 (open-project)

3번 포털에서 만든 앱을 워크스페이스로 가져옵니다. 터미널에 한 줄이면 됩니다. (<앱이름> 은 3번에서 정한 이름)

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회):

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 직접 접속(필요 시):

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

앞 단계가 통과하면 뒤 단계도 거의 그대로 됩니다(같은 코드). 막히면 앞 단계로 돌아가 고치세요.

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

1) 실행

cd ~/projects/<앱이름>
npm run dev             # 코드를 고치면 자동 재시작(핫리로드)

sample listening on :3000 같은 줄이 에러 없이 보이면 기동 성공입니다. (빨간 에러면 보통 ① npm install 안 함 ② 코드 문법 오류 ③ 폴더 밖에서 실행해 .project-env 미로딩 — 셋 중 하나.)

2) 연결만 빠르게 점검 (앱 안 띄우고 DB/파일저장소 연결만 확인):

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 포트 기능을 씁니다:

VS Code 하단 PORTS 탭 → Forward a Port → 포트 번호 3000 입력 (앱이 뜨면 자동 감지되기도 함).
포워딩된 포트 옆 🌐 (Open in Browser) 클릭 → 새 탭에 앱이 열립니다.
- 주소: https://<자동생성>.coder.bokdev.in (본인 전용 임시 URL)

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

경로	의미	정상 응답(예)
`/healthz`	앱이 살아있나	`{"ok":true}`
`/db`	내 Postgres 연결	`{"ok":true,"now":"2026-..."}`
`/s3`	파일저장소(MinIO) 연결	`{"ok":true,"bucket":"...","sampleKeys":[...]}`

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 이 있으면:

cd ~/projects/<앱이름>
podman build -t <앱이름> .       # 현재 폴더의 Dockerfile 로 이미지 빌드

(docker build ... 도 동일하게 동작합니다 — 런타임이 podman 일 뿐입니다.)

마지막에 Successfully tagged localhost/<앱이름>:latest 가 보이면 빌드 성공.

실패하면 빨간 Error: 줄과 몇 번째 STEP 에서 멈췄는지 보세요. 가장 흔한 건 npm install 단계 실패(의존성 문제, package.json 확인).

2) 실행

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번 표와 동일:

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 <ID>.

여기서 빌드 성공 + 3개 엔드포인트 모두 ok:true 면 배포도 거의 그대로 됩니다.

12. Git(Gitea)에 올리기

open-project 로 받은 폴더는 이미 Gitea 저장소에 연결돼 있습니다(3번 포털이 만들어 줬으므로). 따로 저장소를 만들 필요 없이 수정 → 커밋 → push 만 하면 됩니다.

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 를 켠 경우 — 추천 흐름)

12번처럼 git push 합니다.
Kubero가 변경을 감지해 자동으로 다시 빌드·배포합니다(환경변수도 사번 기준으로 자동 주입 — 직접 넣을 필요 없음).

잠시 후 아래 주소로 확인합니다:

https://<앱이름>.playground.bokdev.in

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

나중에 배포 (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로 충분합니다.

문의: 인프라 담당자

29 KiB Raw Blame History