diff --git a/README.md b/README.md index 04229fb..fd40810 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,7 @@ # AI DEV 개발·배포 매뉴얼 (개발자용) -사번 계정(SSO) 하나로 로그인하여 **Coder에서 개발**하고, **Gitea에 push**, **Kubero로 배포**합니다. -DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM)는 워크스페이스에 미리 연결되어 있습니다. - -문서 원본: https://gitea.bokdev.in/playground/MANUAL +행번 계정 하나로 **Coder에서 개발**하고, **Gitea에 push**, **Kubero로 배포**합니다. +DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM - key 제외)는 워크스페이스에 미리 연결되어 있습니다. @@ -31,7 +29,7 @@ DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM)는 워크스페이스에 미 | 개발 중 미리보기 | `https://<자동생성>.coder.bokdev.in` | | 배포된 앱 | `https://<레포명>.playground.bokdev.in` | -모든 서비스는 **사번 계정(SSO)** 으로 로그인합니다. +모든 서비스는 **행번 계정(SSO)** 으로 로그인합니다. 코드에서 쓰는 접속정보(DB·S3)는 `.project-env` 파일로 자동 제공됩니다. 직접 입력할 값이 없습니다. @@ -39,34 +37,35 @@ DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM)는 워크스페이스에 미 1. https://portal.bokdev.in 접속 -2. 사번 계정으로 로그인 - - 아이디: 본인 사번 (예: `2620227`) - - 비밀번호: 본인 비밀번호 (초기 비밀번호는 첫 로그인 후 변경) +2. 행번 계정으로 로그인 + - 아이디: 본인 행번 (예: `2620227`) + - 비밀번호: 본인 비밀번호 (초기 비밀번호: `bok1234!!` + `행번 7자리`) + ![포털 로그인 화면](images/01-login.png) + 3. 이후 Coder·Gitea·Kubero는 추가 로그인 없이 같은 계정으로 열립니다. + - Kubero의 경우 `OAuth로 로그인하기`를 눌러 SSO 로그인이 가능합니다. + ![포털 로그인 화면](images/portal.bokdev.in_.png) -![포털 로그인 화면](images/01-login.png) +## 2. Coder 워크스페이스 만들기 (최초 1회) -비밀번호 변경: 로그인 화면의 "비밀번호 변경" 링크. +Coder 워크스페이스 = 본인 전용 개발 컨테이너(VS Code + 개발 도구 일체). -## 2. 워크스페이스 만들기 (최초 1회) - -워크스페이스 = 본인 전용 개발 컨테이너(VS Code + 개발 도구 일체). +> ⚠️**주의**: 같은 브라우저에 다른 계정으로 Gitea 로그인이 남아 있으면 그 계정으로 연동됩니다. +> 승인 전에 Gitea에서 로그아웃했는지 확인하거나, **시크릿 모드**에서 진행합니다. +> Coder와 Gitea의 로그인 계정이 일치하지 않는 경우 Workspace 생성 후 계정 불일치로 Push가 되지 않을 수 있습니다. 1. https://coder.bokdev.in → **Workspaces** → **Create Workspace** (템플릿: `aidev`) 2. 설정값 입력 - - **Name**: 워크스페이스 이름 (예: `ws-aidev-<사번>`) + - **Name**: 워크스페이스 이름 (예: `ws-aidev-<행번>`) - **External Authentication**: Gitea — **애플리케이션 승인** 클릭 - **CPU / Memory / Disk**: 기본값(2 Core / 4 GiB / 10 GiB) 사용. 추후 변경 가능. - ![Gitea 계정 연동](image-1.png) + ![Gitea 계정 연동](images/02-coder-gitea.png) 3. **Create Workspace** 클릭 4. 최초 빌드는 2~5분 소요. 상태가 **Running**이 되면 완료. -> **주의**: 같은 브라우저에 다른 계정으로 Gitea 로그인이 남아 있으면 그 계정으로 연동됩니다. -> 승인 전에 Gitea에서 로그아웃했는지 확인하거나, 시크릿 창에서 진행합니다. - -워크스페이스는 한 번 만들면 계속 사용합니다. 이후에는 **Start**만 누르면 됩니다([10번](#10-coder-workspace-켜고-끄기)). +> **주의**: 워크스페이스는 한 번 만들면 계속 사용합니다. ## 3. VS Code 열기 @@ -141,7 +140,7 @@ new-project myapp # 예제를 ~/projects/myapp 으로 복사 + .p cd ~/projects/myapp git init -b main git add . -git commit -m "init" +git commit -m "init project" ``` **(3) VS Code로 폴더 열기**: **File → Open Folder…** → `/home/coder/projects/myapp` → OK @@ -224,7 +223,8 @@ curl 127.0.0.1:3000/s3 # {"ok":true,"bucket":...} S3 연결 ### 9-1. Gitea 원격 레포 생성 (앱당 1회) -1. https://gitea.bokdev.in → 우측 상단 **`+` → New Repository** +1. https://gitea.bokdev.in/playground → 우측 상단 **`+` → New Repository** + ![새 저장소 만들기](images/make-new-repository.png) 2. **Owner: `playground`** 로 변경, Repository Name 입력 (예: `myapp`) 3. README / .gitignore / License 는 체크하지 않음(빈 저장소여야 함) → **Create Repository** @@ -240,22 +240,22 @@ git push -u origin main ### 9-3. Kubero에 앱 추가 (앱당 1회) +> TODO: Kubero 배포 오류 수정 필요 + `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. 생성하면 빌드·배포가 실행됩니다. +2. **`playground`** 파이프라인 선택 +3. **Production** 아래의 `+` 버튼을 클릭해 앱을 추가 +4. App Name과 환경 ENVIRONMENT VARIABLES 추가 + ![Kubero 배포 앱 추가](images/kubero-pipeline.png) + - `.project-env` 파일을 업로드 하면 자동으로 파싱되어 등록됩니다. > 자동 빌드는 현재 미연동입니다. **코드 수정 후에는 push 하고 Kubero에서 해당 앱의 빌드를 다시 실행합니다.** ### 9-4. 확인 -배포·재시작 직후 약 1~2분은 초기화(코드 다운로드·설치) 시간입니다. 404가 나와도 기다린 뒤 다시 확인합니다. +배포·재시작 직후 약 1~2분은 초기화(코드 다운로드·설치) 시간입니다. 일시적으로 404가 나오는 경우, 잠시 기다린 후 Ctrl + Shift + R로 강력 새로고침 후 확인해주세요. ```bash curl https://<레포명>.playground.bokdev.in/healthz # {"ok":true} @@ -267,16 +267,16 @@ curl https://<레포명>.playground.bokdev.in/s3 문제가 있으면 Kubero에서 해당 앱의 빌드/배포 로그를 확인합니다. 로그에 `listening on :3000` 이 보이면 기동 성공입니다. -## 10. Coder Workspace 켜고 끄기 -- Coder workspace 재기동이 필요한 경우: Coder 워크스페이스 화면에서 **Stop** -- 다시 사용: **Start** (VS Code Web 아이콘이 뜰 때까지 대기) -- `~/projects` 만 보존됩니다. 그 외 경로의 파일은 사라질 수 있습니다. +## FAQ -## 문제 해결 +- Coder Workspace 켜고 끄기 + - Coder workspace 재기동이 필요한 경우: Coder 워크스페이스 화면에서 **Stop** + - 다시 사용: **Start** (VS Code Web 아이콘이 뜰 때까지 대기) + - `~/projects` 만 보존됩니다. 그 외 경로의 파일은 사라질 수 있습니다. -- **로그인을 서비스마다 해야 하나요** → 아니요. 사번 계정 SSO 하나로 전부 로그인됩니다. -- **파일이 사라졌어요** → `~/projects` 밖에 저장한 경우 파일이 유실될 수 있습니다([3번](#3-vs-code-열기)). +- **로그인을 서비스마다 해야 하나요** → 아니요. 행번 계정 SSO 하나로 전부 로그인됩니다. +- **Coder에서 파일이 사라졌어요** → `~/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회)). @@ -290,6 +290,8 @@ curl https://<레포명>.playground.bokdev.in/s3 - **DB가 비어 있음** → 정상입니다. 빈 전용 스키마가 제공되며 테이블은 직접 생성합니다. - **K8s에 직접 접근하고 싶어요** → 직원은 K8s에 직접 접근하지 않습니다. Coder·Gitea·Kubero로 개발·배포가 완결됩니다. ---- -문의: 인프라 담당자 \ No newline at end of file +## 문의 +- IT 전략국 클라우드팀 김창록 팀장 +- IT 전략국 정보시스템개발팀 박성록 과장 +- IT 전략국 클라우드팀 이혜민 조사역 \ No newline at end of file diff --git a/images/01-login.png b/images/01-login.png new file mode 100644 index 0000000..988f69e Binary files /dev/null and b/images/01-login.png differ diff --git a/images/02-coder-gitea.png b/images/02-coder-gitea.png new file mode 100644 index 0000000..790523f Binary files /dev/null and b/images/02-coder-gitea.png differ diff --git a/images/08-deployed-app.png b/images/08-deployed-app.png new file mode 100644 index 0000000..0c64831 Binary files /dev/null and b/images/08-deployed-app.png differ diff --git a/images/coder-ports-preview.png b/images/coder-ports-preview.png new file mode 100644 index 0000000..89fb86e Binary files /dev/null and b/images/coder-ports-preview.png differ diff --git a/images/kubero-pipeline.png b/images/kubero-pipeline.png new file mode 100644 index 0000000..8d8d88b Binary files /dev/null and b/images/kubero-pipeline.png differ diff --git a/images/make-new-repository.png b/images/make-new-repository.png new file mode 100644 index 0000000..f752f00 Binary files /dev/null and b/images/make-new-repository.png differ diff --git a/images/portal.bokdev.in_.png b/images/portal.bokdev.in_.png new file mode 100644 index 0000000..b54a6c0 Binary files /dev/null and b/images/portal.bokdev.in_.png differ