Files

이혜민(2620227) 57377e849f update manual and rename to README

2026-07-01 04:57:17 +00:00

28 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. Portal 로그인

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

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

1. Coder 로그인

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

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

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

로그인하면 Workspaces 화면. Create Workspace 클릭 (또는 Templates → aidev 선택)
설정값 입력
- Name: 워크스페이스 이름 (예: ws-aidev-<사번> 또는 자유롭게)
- External Authentication : Gitea(그대로 둠)
- CPU / Memory / Home disk size: 기본값(2 Core / 4 GiB / 10 GiB)으로 두면 됩니다. 필요하면 나중에 늘릴 수 있습니다.
- (Optional) Gitea 계정 연동
  - git 원격 계정을 사전 연동할 수 있습니다. 지금 연동하지 않아도 추후 workspace 터미널에서 연동 가능합니다.
  - External Authentication - 애플리케이션 승인
Create Workspace 클릭
워크스페이스가 빌드됩니다 (처음엔 이미지 다운로드로 2~5분 걸릴 수 있습니다. VS Code Web 까지 아이콘이 표시될 때까지 기다리세요).
- 상태가 Running 이 되면 준비 완료.

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

3. VS Code 열기

워크스페이스 화면에서 VS Code Web 버튼(두번째 아이콘) 클릭
브라우저에 VS Code가 열리고, 자동으로 /home/coder/projects 폴더가 열립니다. (Yes. I trust the authors 클릭)
그 안에 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·확장)가 공유합니다.

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

확인:

echo $ANTHROPIC_BASE_URL   # https://litellm.bok.or.kr 가 나오면 정상
claude                     # Claude Code CLI 실행

echo $GOOGLE_GEMINI_BASE_URL  # https://litellm.bok.or.kr 가 나오면 정상
gemini                     # Gemini CLI 실행

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

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

예:

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) 프로젝트 만들기 — 터미널에 입력:

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)에서:

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

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

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

단계	무엇으로	무엇을 확인	어디서
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번입니다.

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

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

1) 빌드

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) 실행

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

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 이라 자동 삭제됨).
- 종료되지 않는 경우
```
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) 워크스페이스 터미널에서 올리기

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: 현재 안됨)

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번 로컬에서 먼저 통과했는지.

자주 묻는 것

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로 충분합니다.

문의: 인프라 담당자

28 KiB Raw Blame History