From 57377e849f69a8952f2fc074c4e5275d048dc628 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=ED=98=9C=EB=AF=BC=282620227=29?= Date: Wed, 1 Jul 2026 04:57:17 +0000 Subject: [PATCH] update manual and rename to `README` --- USER-MANUAL.md => README.md | 351 ++++++++++++++++++------------------ 1 file changed, 171 insertions(+), 180 deletions(-) rename USER-MANUAL.md => README.md (61%) diff --git a/USER-MANUAL.md b/README.md similarity index 61% rename from USER-MANUAL.md rename to README.md index 62a73f0..a9a0174 100644 --- a/USER-MANUAL.md +++ b/README.md @@ -55,13 +55,13 @@ DB·파일저장소(MinIO)·AI(LiteLLM)·Git(Gitea)·배포(Kubero)가 미리 --- -## 1. 포털(Backstage) 로그인 +## 1. Portal 로그인 -1. 브라우저에서 **https://backstage.bokdev.in** 접속합니다. +1. 브라우저에서 **https://portal.bokdev.in** 접속합니다. 2. 로그인 화면에서 **사번 계정**으로 로그인합니다. - **아이디** = 본인 사번 (예: `2620227`) - **비밀번호** = 본인 비밀번호 (초기 비밀번호를 받았다면 첫 로그인 후 변경 권장) -3. 로그인은 회사 통합 인증(SSO)으로 처리됩니다. **여기서 한 번 로그인하면 Coder·Gitea 는 다시 로그인 없이 자동으로 열립니다.** Kubero 등 그 밖의 도구는 클릭 후 로그인 화면이 한 번 더 나올 수 있습니다(Kubero 는 같은 사번 계정으로 로그인). +3. 로그인은 통합 인증(SSO)으로 처리됩니다. **여기서 한 번 로그인하면 Coder·Gitea 는 다시 로그인 없이 자동으로 열립니다.** Kubero는 `OAuth로 로그인`을 눌러 로그인할 수 있습니다. ![포털 로그인 화면](images/01-login.png) @@ -69,138 +69,95 @@ DB·파일저장소(MinIO)·AI(LiteLLM)·Git(Gitea)·배포(Kubero)가 미리 --- -## 2. 홈 대시보드 둘러보기 +## 1. Coder 로그인 -로그인하면 **홈(카드 대시보드)** 이 나옵니다. 자주 쓰는 도구로 바로 가는 카드들이 있습니다. **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번부터 진행해도 됩니다. 추천 순서는 위 흐름도(맨 위)를 참고하세요. +1. 브라우저에서 **https://coder.bokdev.in** 접속 +2. 로그인 + - **Username**: 본인 행번 (예: `2620227`) + - **Password**: `bok1234!!` + 본인 사번 (예: `bok1234!!2620227`) + → 최초 로그인 후 비밀번호를 바꾸시기 바랍니다. (우측 상단 계정 메뉴 → `Account` → `Security`) --- -## 3. 포털에서 앱 만들기 ("AI DEV 앱 만들기") +## 2. 워크스페이스 만들기 (최초 1회) -새 앱을 시작하는 **표준 방법**입니다. 이 한 번으로 **저장소(Gitea) 생성 + 샘플 코드 채우기 + 포털 등록**이 자동으로 됩니다. -(예전처럼 Gitea에서 직접 저장소를 만들 필요가 없습니다.) +워크스페이스 = 본인 전용 개발용 컨테이너(VS Code + 각종 도구가 깔린 PC). -### 3-1. 템플릿 실행 +1. 로그인하면 **Workspaces** 화면. **`Create Workspace`** 클릭 (또는 **Templates → `aidev`** 선택) +2. 설정값 입력 + - **Name**: 워크스페이스 이름 (예: `ws-aidev-<사번>` 또는 자유롭게) + - **External Authentication** : Gitea(그대로 둠) + - **CPU / Memory / Home disk size**: 기본값(2 Core / 4 GiB / 10 GiB)으로 두면 됩니다. 필요하면 나중에 늘릴 수 있습니다. -1. 포털 사이드바에서 **Create**(또는 상단 **Create...**) 클릭. -2. **"AI DEV 앱 만들기"** 템플릿의 **CHOOSE** 클릭. + * (Optional) Gitea 계정 연동 + * git 원격 계정을 사전 연동할 수 있습니다. 지금 연동하지 않아도 추후 workspace 터미널에서 연동 가능합니다. + * `External Authentication` - `애플리케이션 승인` + ![Gitea 계정 연동](image-1.png) -![템플릿 선택](images/03-template-choose.png) +3. **`Create Workspace`** 클릭 +4. 워크스페이스가 빌드됩니다 (**처음엔 이미지 다운로드로 2~5분** 걸릴 수 있습니다. VS Code Web 까지 아이콘이 표시될 때까지 기다리세요). + - 상태가 **Running** 이 되면 준비 완료. -### 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 <앱이름>`)에서 씁니다. +> 이 워크스페이스는 한번 만들면 계속 사용합니다. 한번 만들어진 워크스페이스는 가상 PC처럼 **Start** 만 누르면 됩니다. --- -# 〔개발 환경 준비 — 처음 한 번만〕 +## 3. VS Code 열기 -## 4. Coder 워크스페이스 만들기 (최초 1회) +1. 워크스페이스 화면에서 **`VS Code Web`** 버튼(두번째 아이콘) 클릭 +2. 브라우저에 VS Code가 열리고, 자동으로 **`/home/coder/projects`** 폴더가 열립니다. (Yes. I trust the authors 클릭) +3. 그 안에 **`sample`** 폴더가 이미 있습니다 — 참조용 예제입니다(직접 고치지 말고 복사해 쓰세요, 7번 참고). -워크스페이스 = 본인 전용 개발용 컨테이너(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`** 아래에 두세요. **이 폴더만 영구 보존**됩니다. +> 작업 파일은 반드시 **`/home/coder/projects`** 아래에 두세요. 이 폴더만 영구 보존됩니다. > (워크스페이스를 stop/재시작해도 유지. 그 밖의 위치는 사라질 수 있습니다.) --- -## 6. AI 에이전트 사용 설정 (최초 1회) — LiteLLM 키 입력 +## 4. 미리 연결된 것들 (별도 설정 불필요) -Claude Code / Codex / Gemini 가 사내 AI 게이트웨이를 쓰려면 **본인 LiteLLM 키**가 필요합니다. -키는 **한 곳에만** 넣으면 모든 도구가 공유합니다. +새 워크스페이스에는 아래가 자동으로 준비돼 있습니다. -1. 터미널 열기: VS Code 상단 메뉴(작대기 3개) **Terminal → New Terminal** (화면 아래에 터미널 창이 뜸). -2. 다음을 입력하고, 안내가 나오면 발급받은 본인 키(`sk-...`)를 붙여넣습니다: +| 항목 | 내용 | +|---|---| +| **개발 도구** | 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·확장)가 공유합니다. + +1. 터미널 열기: VS Code 좌상단 맨위 메뉴 버튼(작대기 3개) **Terminal → New Terminal** +2. 화면 아래 터미널 창이 나오면, 다음 명령을 입력하고, 안내가 나오면 발급받은 본인 키(`sk-...`)를 붙여넣습니다: ```bash update-litellm-key ``` ``` LiteLLM virtual key 입력 (sk-...): sk-여기에-본인-키-붙여넣기 - 키 갱신 완료. 현재 터미널에 즉시 적용됨. + 키 갱신 완료 (len=25). 현재 터미널에 즉시 적용됨. ``` - > 이 명령은 키를 저장하고 **현재 터미널에 바로 적용**합니다. 새 터미널을 열거나 `source` 할 필요 없습니다. 키를 바꿀 때도 같은 명령을 다시 쓰면 됩니다. + > `update-litellm-key` 는 키를 파일에 저장하고 **현재 터미널에 바로 적용**합니다. + > 터미널을 새로 열거나 `source` 할 필요가 없습니다. 키를 바꿀 때도 같은 명령을 다시 쓰면 됩니다. 3. 확인: ```bash echo $ANTHROPIC_BASE_URL # https://litellm.bok.or.kr 가 나오면 정상 claude # Claude Code CLI 실행 ``` + ```bash + echo $GOOGLE_GEMINI_BASE_URL # https://litellm.bok.or.kr 가 나오면 정상 + gemini # Gemini CLI 실행 + ``` + ```bash + echo $OPENAI_BASE_URL # https://litellm.bok.or.kr/v1 가 나오면 정상 + codex # Codex CLI 실행 + ``` -각 도구의 **기본 모델**은 미리 설정돼 있습니다: +각 도구의 **기본 모델**은 사내 게이트웨이에 맞춰 미리 설정돼 있습니다(바꾸려면 각 설정 파일 수정): | 도구 | 기본 모델 | 설정 파일 | |---|---|---| @@ -208,59 +165,73 @@ Claude Code / Codex / Gemini 가 사내 AI 게이트웨이를 쓰려면 **본인 | Codex | `gpt-5.5` | `~/.codex/config.toml` | | Gemini | `gemini-3.1-pro-preview` | `~/.gemini/settings.json` | -> 키는 본인 워크스페이스 안에만 저장되고, 코드/깃에는 올라가지 않습니다. 게이트웨이 주소는 이미 설정돼 있으니 건드릴 필요 없습니다. +> 키는 본인 워크스페이스 안에만 저장되고, 코드/깃에는 올라가지 않습니다. +> 게이트웨이 주소(`https://litellm.bok.or.kr`)는 이미 설정돼 있으니 건드릴 필요 없습니다. --- -## 7. Git(Gitea) 사용 — 최초 1회 승인 +## 6. Git(Gitea) 사용 — 최초 1회 승인 코드 저장소는 사내 **Gitea**(https://gitea.bokdev.in)입니다. 토큰 입력 없이 자동 인증됩니다. -1. 터미널에서 처음 `git clone`/`git push`(또는 8번 `open-project`)를 하면 **Gitea 승인 화면**으로 안내됩니다. +1. 터미널에서 처음 `git clone` / `git push` 등을 하면, **Gitea 승인 화면**으로 안내됩니다. - 또는 Coder 화면의 **`Gitea`** external auth 항목에서 **Authorize** 를 미리 눌러도 됩니다. 2. 한 번 **Authorize(승인)** 하면, 이후로는 비밀번호 입력 없이 clone/push 가 됩니다. ---- - -# 〔앱마다 반복하는 개발·배포 흐름〕 - -## 8. 내 앱 가져오기 (open-project) - -3번 포털에서 만든 앱을 워크스페이스로 가져옵니다. **터미널에 한 줄이면 됩니다.** -(`<앱이름>` 은 3번에서 정한 이름) - +예: ```bash -open-project <앱이름> +cd ~/projects + +## 만약 새로운 repo를 다운로드 하고 싶을 경우 +git clone https://gitea.bokdev.in//.git + +## 사용예 +git clone https://gitea.bokdev.in/playground/sample.git + +## 새로운 버전으로 동기화 +cd ~/projects/sample +git add . +git pull +# gitea 행번 / 비밀번호 ``` -이 명령이 자동으로: -- 포털이 만든 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번)에서 관리합니다. - --- +## 7. 새 프로젝트 시작하기 (sample 복사) -## 9. 개발하기 +`~/projects/sample` 은 바로 돌려볼 수 있는 Node 예제이며 **읽기 전용 참조**입니다. +직접 고치지 말고, **`new-project` 명령으로 복사**해서 본인 프로젝트를 시작하세요. -(8번에서 **본인 프로젝트 폴더를 Open Folder 해 둔 상태**에서) +**(1) 터미널 열기** — VS Code 상단 메뉴 **Terminal → New Terminal** (화면 아래쪽에 터미널 창이 뜹니다) + +**(2) 프로젝트 만들기** — 터미널에 입력: +```bash +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)에서: +```bash +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번. @@ -271,7 +242,7 @@ npm install # 안 하면 실행이 실패합니다 ``` - 코드에서는 그냥 `process.env.DATABASE_URL`, `process.env.S3_*` 로 쓰면 됩니다. 값은 `.project-env` 에 이미 들어 있습니다. -### 9-1. AI 도구를 잘 쓰는 법 (팁) +### 8-1. AI 도구를 잘 쓰는 법 (팁) - **항상 프로젝트 폴더 안에서 실행**하세요. AI는 "지금 폴더"의 파일을 읽어 맥락을 잡습니다. - **`CLAUDE.md` 를 활용**하세요. 샘플에는 프로젝트 규칙(컨테이너 개발, 배포 방식, 비밀값 금지 등)을 적은 `CLAUDE.md`가 들어 있고, AI가 자동으로 읽습니다. 규칙·주의사항을 여기에 적어두면 그대로 따릅니다. @@ -279,7 +250,7 @@ npm install # 안 하면 실행이 실패합니다 - **확인은 직접**: AI가 만든 코드도 10번(로컬 실행)·11번(컨테이너)으로 **반드시 본인이 동작 확인** 후 커밋하세요. - 키가 안 먹으면(401) → 6번 재실행. 모델 오류(400)면 → 6번 표의 모델명. -### 9-2. bkit — AI 개발 보조 플러그인 (선택, 권장) +### 8-2. bkit — AI 개발 보조 플러그인 (선택, 권장) **bkit**(Vibecoding Kit, https://www.bkit.ai/ )은 Claude Code 에 **체계적 개발 절차(계획→설계→구현→검증)** 와 전문 스킬을 더해주는 플러그인입니다. "무엇을 만들지"만 설명하면 단계적으로 진행해 줍니다. @@ -303,7 +274,7 @@ claude --- -## 10. 로컬에서 실행하고 브라우저로 확인하기 +## 9. 로컬에서 실행하고 브라우저로 확인하기 코드를 바로 실행해 동작을 확인하는 단계입니다(가장 빠름). @@ -355,65 +326,93 @@ curl 127.0.0.1:3000/s3 # 버킷명 + 파일목록 일부 --- -## 11. 컨테이너로 빌드해서 확인하기 (podman) +## 10. 컨테이너로 빌드해서 확인하기 (podman) — 배포 전 점검 -10번은 코드를 그냥 실행한 것이고, 실제 배포는 **컨테이너 이미지**로 띄웁니다. -배포 전에 **같은 방식(컨테이너)으로 한 번 돌려보면** 배포 후 문제를 미리 잡을 수 있습니다. (선택이지만 권장) +9번은 코드를 그냥 실행한 것이고, 실제 배포(Coolify)는 **Dockerfile 로 컨테이너를 빌드**해서 띄웁니다. +배포 전에 **같은 방식(컨테이너)으로 한 번 돌려보면** 배포 후 문제를 미리 잡을 수 있습니다. +(Coolify 도 똑같은 `Dockerfile` 을 쓰므로, **여기서 빌드가 되면 12번 배포 빌드도 거의 됩니다.**) -**1) 빌드** — 프로젝트에 `Dockerfile` 이 있으면: +**1) 빌드** ```bash -cd ~/projects/<앱이름> -podman build -t <앱이름> . # 현재 폴더의 Dockerfile 로 이미지 빌드 +cd ~/projects/<본인 프로젝트> +podman build -t myapp . # 현재 폴더의 Dockerfile 로 이미지 빌드 ``` -(`docker build ...` 도 동일하게 동작합니다 — 런타임이 podman 일 뿐입니다.) +(`docker build ...` 도 동일하게 동작합니다 — 실제 런타임이 podman 일 뿐입니다.) -마지막에 `Successfully tagged localhost/<앱이름>:latest` 가 보이면 **빌드 성공**. -- **실패하면** 빨간 `Error:` 줄과 **몇 번째 STEP 에서 멈췄는지** 보세요. 가장 흔한 건 `npm install` 단계 실패(의존성 문제, `package.json` 확인). +**빌드 로그 읽는 법** — 한 줄씩 `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) 실행** ```bash -podman run --rm -p 3000:3000 --env-file .project-env <앱이름> +podman run --rm -p 3000:3000 --env-file .project-env myapp # 빌드한 이미지를 컨테이너로 실행 +# 또는 (빌드+실행 한 번에): podman compose up --build ``` -- `--env-file .project-env` 로 DB/S3 값을 컨테이너에 넣어줍니다(없으면 `/db`·`/s3` 가 실패). -- 기동되면 10번처럼 `listening on :3000` 이 보입니다. +- `--env-file .project-env` 로 DB/S3 값을 컨테이너에 넣어줍니다(이게 없으면 컨테이너 안에서 `/db`·`/s3` 가 실패합니다). +- 기동되면 9번과 똑같이 `sample listening on :3000` 이 보입니다. -**3) 동작 확인** — 접속은 **`127.0.0.1`** 로 (가끔 `localhost` 가 안 잡힘). 기대 응답은 10번 표와 동일: +**3) 동작 확인** — 컨테이너 접속 확인은 **`127.0.0.1`** 로 하세요(`localhost` 가 간혹 안 잡힙니다). 기대 응답은 9번 표와 동일합니다: ```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":...} +curl 127.0.0.1:3000/s3 # {"ok":true,"bucket":"coolify-user-data",...} ``` -- 브라우저로 보려면 10번처럼 **PORTS → Forward 3000 → Open in Browser**. -- 끝나면 터미널에서 **Ctrl+C** 로 멈춥니다(`--rm` 이라 자동 삭제). 안 멈추면 `podman ps` → `podman stop `. +- 브라우저로 보려면 9번과 동일하게 **PORTS 패널 → Forward Port 3000 → Open in Browser**(`https://<자동생성>.coder.bokdev.in`). +- 확인이 끝나면 터미널에서 **Ctrl+C** 로 컨테이너를 멈춥니다(`--rm` 이라 자동 삭제됨). + * 종료되지 않는 경우 + ```bash + podman ps + podman stop {이름 또는 ID} + ``` -> 여기서 **빌드 성공 + 3개 엔드포인트 모두 `ok:true`** 면 배포도 거의 그대로 됩니다. +- 빌드/실행 권한은 워크스페이스에 이미 설정돼 있습니다(별도 설정 불필요). + +> 여기서 **빌드 성공 + 3개 엔드포인트 모두 `ok:true`** 면 Coolify 배포도 거의 그대로 됩니다. 안 되면 코드/Dockerfile 을 먼저 고치세요. --- -## 12. Git(Gitea)에 올리기 +## 11. Gitea(git)에 올리기 -`open-project` 로 받은 폴더는 **이미 Gitea 저장소에 연결돼 있습니다**(3번 포털이 만들어 줬으므로). 따로 저장소를 만들 필요 없이 **수정 → 커밋 → push** 만 하면 됩니다. +`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) 워크스페이스 터미널에서 올리기** ```bash -cd ~/projects/<앱이름> +cd ~/projects/myapp +git init git add . -git commit -m "기능 구현" -git push +git commit -m "first commit(혹은 자유롭게)" +git branch -M main +git remote add origin https://gitea.bokdev.in/<본인사번>/myapp.git +git push -u origin main ``` -- 인증은 자동입니다(7번 Gitea 승인을 한 번 했다면). 처음이면 승인 화면이 한 번 뜹니다. -- 이후로는 위 3줄만 반복하면 됩니다. +- 인증은 자동입니다(6번 Gitea 승인을 한 번 했다면). 처음이면 승인 화면이 한 번 뜹니다. +- 이후 수정한 뒤에는 `git add . && git commit -m "..." && git push` 만 반복하면 됩니다. -> **`.project-env` 는 git에 안 올라갑니다**(자격증명 보호 — 정상). `git status` 에 안 보여도 맞습니다. -> 배포 환경의 DB/S3 값은 **포털이 자동으로 넣어주므로** 따로 등록할 필요가 없습니다(13번). +> **순서는 상관없습니다.** 코드를 먼저 만들고(권장) 나중에 저장소를 만들어도 됩니다. `git push` 시점에 Gitea 저장소만 있으면 됩니다. +> **`.project-env` 는 git에 올라가지 않습니다**(DB·S3 자격증명 보호 — 정상). `git status` 에 안 보여도 맞습니다. --- -## 13. 배포하고 확인하기 (Kubero) +## 12. 배포하고 확인하기 (Kubero) 배포는 **Kubero**가 담당합니다. 좋은 소식: 3번에서 **"생성 직후 Kubero 로 배포"를 켰다면 배포 통로가 이미 자동으로 설정**돼 있습니다. 그래서 개발자가 할 일은 사실상 **`git push`(12번)** 뿐입니다. -### 자동 배포 (3번에서 deployNow 를 켠 경우 — 추천 흐름) +### 자동 배포 (TODO: 현재 안됨) 1. 12번처럼 **`git push`** 합니다. 2. Kubero가 변경을 감지해 **자동으로 다시 빌드·배포**합니다(환경변수도 사번 기준으로 **자동 주입** — 직접 넣을 필요 없음). @@ -450,14 +449,6 @@ git push --- -## 14. 워크스페이스 켜고 끄기 - -- **그만 쓸 때**: Coder 워크스페이스 화면 → **Stop** (자원 절약. `~/projects` 파일은 보존). -- **다시 쓸 때**: **Start** (수십 초 내 기동). -- **업데이트 안내(`Update` 버튼)** 가 뜨면 눌러서 최신 환경으로 갱신하세요. `~/projects` 파일은 유지됩니다. - ---- - ## 자주 묻는 것 - **Q. 로그인을 서비스마다 다시 해야 하나요?** → **Coder·Gitea 는** 포털 로그인만으로 자동 로그인됩니다(SSO). **Kubero** 는 클릭 후 로그인 화면이 한 번 더 나올 수 있으나 **같은 사번 계정**으로 들어가면 됩니다. **OpenEverest·MinIO** 는 별도 로그인이라 접근이 막히면 인프라 담당자에게 문의하세요.