용어 통일 및 문구 다듬기

- '레포' → '레포지토리'(git 원격 저장소·URL 지칭 시), URL 이름 placeholder '<레포명>' → '<프로젝트명>'으로 통일 - 9-1 제목 변경에 맞춰 앵커 링크 동기화 - 섹션 0: 서비스 설명 정리(Gitea=원격 레포지토리, Kubero=k8s 기반/Coolify=Docker 기반), 미리보기 행 정리 - 9-3A/9-3B 제목에 토글 펼침 안내 문구 추가 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-10 17:52:16 +09:00
parent d49ab5c642
commit 29d4828fb7
1 changed files with 31 additions and 32 deletions
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM - key 제외)는 워크스페

 ```
 [최초 1회] 로그인(1) → 워크스페이스 생성(2) → VS Code(3) → AI 키 등록(5)
-[앱마다]   new-project + git init(6) → 개발·커밋(7) → 로컬 확인(8) → 레포 생성·push·배포(Kubero/Coolify)(9) → 포털 공유(9-5)
+[앱마다]   new-project + git init(6) → 개발·커밋(7) → 로컬 확인(8) → 레포지토리 생성·push·배포(Kubero/Coolify)(9) → 포털 공유(9-5)
 ```

 ## 0. 서비스 종류
@@ -25,12 +25,11 @@ DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM - key 제외)는 워크스페
 |---|---|
 | AI DEV 포털 (시작점) | https://portal.bokdev.in |
 | Coder (개발 워크스페이스) | https://coder.bokdev.in |
-| Gitea (코드 저장소) | https://gitea.bokdev.in |
-| Kubero (배포 · 후보) | https://kubero.bokdev.in |
-| Coolify (배포 · 후보) | https://coolify.bokdev.in |
-| 개발 중 미리보기 | `https://<자동생성>.coder.bokdev.in` |
-| 배포된 앱 (Kubero) | `https://<레포명>.playground.bokdev.in` |
-| 배포된 앱 (Coolify) | `https://<레포명>.apps.bokdev.in` |
+| Gitea (코드 저장소, 원격 레포지토리) | https://gitea.bokdev.in |
+| Kubero (배포(k8s 기반)) | https://kubero.bokdev.in |
+| Coolify (배포(Docker 기반)) | https://coolify.bokdev.in |
+| 배포된 앱 (Kubero) | `https://<프로젝트명>.playground.bokdev.in` |
+| 배포된 앱 (Coolify) | `https://<프로젝트명>.apps.bokdev.in` |

 모든 서비스는 **행번 계정(SSO)** 으로 로그인합니다.

@@ -43,8 +42,8 @@ DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM - key 제외)는 워크스페
 1. https://portal.bokdev.in 접속
   <!-- TODO: 포털 주소 portal.bokdev.in / backstage.bokdev.in 중 확정 -->
 2. 행번 계정으로 로그인
-   - 아이디: 본인 행번 (예: `2620227`)
-   - 비밀번호: 본인 비밀번호 (초기 비밀번호: `bok1234!!` + `행번 7자리`)
+   - 아이디: 본인 행번 (예: `2620227`)  
+   - 비밀번호: 본인 비밀번호 (초기 비밀번호: `bok1234!!` + `행번 7자리`)  
   ![포털 로그인 화면](images/01-login.png)

 3. 이후 Coder·Gitea·Kubero는 추가 로그인 없이 같은 계정으로 열립니다.
@@ -138,7 +137,7 @@ cd ~/projects
 cd sample && git pull && cd ..   # 예제 최신화
 new-project myapp                # 예제를 ~/projects/myapp 으로 복사 + .project-env 자동 생성
 ```
-`myapp`은 예시입니다. 이 이름은 Gitea 레포명으로 설정할 이름과 동일하게 맞추시면 되고, 소문자·숫자·하이픈만 사용합니다.
+`myapp`은 예시입니다. 이 이름(프로젝트 명)은 Gitea 레포지토리명과 동일하게 맞추시면 되고, 영어·숫자·하이픈만 사용합니다.

 **(2) git 초기화** — 개발 시작 시점에 합니다. 커밋 이력을 처음부터 관리하기 위함이며, 원격(Gitea) 연결은 배포 단계([9번](#9-배포-gitea--kubero--coolify))에서 합니다:
 ```bash
@@ -223,21 +222,21 @@ curl 127.0.0.1:3000/s3        # {"ok":true,"bucket":...} S3 연결

 ## 9. 배포 (Gitea → Kubero / Coolify)

-배포 단위: Gitea `playground` 조직의 레포 1개 = 배포 앱 1개.
-배포 주소는 사용하는 도구에 따라 다릅니다 — **Kubero → `https://<레포명>.playground.bokdev.in`**, **Coolify → `https://<레포명>.apps.bokdev.in`**.
+배포 단위: Gitea `playground` 조직의 레포지토리 1개 = 배포 앱 1개.
+배포 주소는 사용하는 도구에 따라 다릅니다 — **Kubero → `https://<프로젝트명>.playground.bokdev.in`**, **Coolify → `https://<프로젝트명>.apps.bokdev.in`**.

 배포 도구는 **Kubero**와 **Coolify** 중 하나를 사용합니다.  
-**Gitea 레포 생성([9-1](#9-1-gitea-원격-레포-생성-앱당-1회))과 push([9-2](#9-2-push))는 두 도구 공통**이며, 이후 사용하는 도구에 따라 [9-3A(Kubero)](#9-3a-kubero에-앱-추가-앱당-1회) 또는 [9-3B(Coolify)](#9-3b-coolify에-앱-추가-앱당-1회)를 따릅니다.
+**Gitea 레포지토리 생성([9-1](#9-1-gitea-원격-레포지토리-생성-앱당-1회))과 push([9-2](#9-2-push))는 두 도구 공통**이며, 이후 사용하는 도구에 따라 [9-3A(Kubero)](#9-3a-kubero에-앱-추가-앱당-1회) 또는 [9-3B(Coolify)](#9-3b-coolify에-앱-추가-앱당-1회)를 따릅니다.

 | 항목 | Kubero | Coolify |
 |---|---|---|
-| 배포 주소 | `https://<레포명>.playground.bokdev.in` | `https://<레포명>.apps.bokdev.in` |
+| 배포 주소 | `https://<프로젝트명>.playground.bokdev.in` | `https://<프로젝트명>.apps.bokdev.in` |
 | 배포 위치 | `playground` 파이프라인에 앱 추가 | `aidev` 팀 → `aidev` 프로젝트에 앱 추가 |
 | 코드 수정 반영 | push 후 **수동 재빌드** (자동 빌드 미연동) | push 시 **자동 재빌드·배포** (webhook 설정 시, [9-3B](#9-3b-coolify에-앱-추가-앱당-1회)) |
 | 환경변수 입력 | `.project-env` 업로드 → 자동 파싱 | `.project-env` 값을 붙여넣기 (Developer view) |
 | 빌드 방식 | Dockerfile | Dockerfile |

-### 9-1. Gitea 원격 레포 생성 (앱당 1회)
+### 9-1. Gitea 원격 레포지토리 생성 (앱당 1회)

 1. https://gitea.bokdev.in/playground → 우측 상단 **`+` → New Repository**  
   ![새 저장소 만들기](images/make-new-repository.png)
@@ -255,7 +254,7 @@ git push -u origin main
 - 최초 push 시 Gitea 승인 화면이 뜨면 **Authorize** 클릭([2번](#2-워크스페이스-만들기-최초-1회)에서 승인했다면 생략됨).
 - 이후 수정 반영: `git add . && git commit -m "..." && git push`

-### 9-3A. Kubero에 앱 추가 (앱당 1회)
+### 9-3A. Kubero에 앱 추가 (앱당 1회 - 삼각형을 눌러 확인하세요)

 <details>
 <summary><b>Kubero로 배포</b> — 도메인 <code>*.playground.bokdev.in</code> · 클릭해서 펼치기</summary>
@@ -273,7 +272,7 @@ git push -u origin main

 </details>

-### 9-3B. Coolify에 앱 추가 (앱당 1회)
+### 9-3B. Coolify에 앱 추가 (앱당 1회 - 삼각형을 눌러 확인하세요)

 <details>
 <summary><b>Coolify로 배포</b> — 도메인 <code>*.apps.bokdev.in</code> · 클릭해서 펼치기</summary>
@@ -288,13 +287,13 @@ Coolify는 "**push → Dockerfile로 자동 빌드·배포**" 방식입니다.
 4. **Repository URL**에 **전체 주소**를 입력 후 **`Check Repository`**:
   `https://gitea.bokdev.in/playground/myapp.git`
   (`playground/myapp` 처럼 줄여 쓰면 실패합니다.)
-   > **비공개(private) 레포일 때** — `Public Repository` 로도 받을 수 있습니다. URL에 Gitea 토큰을 끼워 넣습니다:
+   > **비공개(private) 레포지토리일 때** — `Public Repository` 로도 받을 수 있습니다. URL에 Gitea 토큰을 끼워 넣습니다:
   > `https://<토큰>@gitea.bokdev.in/playground/myapp.git`
   > - 토큰 발급: Gitea → 우측 상단 프로필 → **Settings → Applications → Generate New Token**. 이름 지정 후 **`repository` 읽기 권한(Read)** 만 체크 → 생성. 표시되는 토큰은 **이때 한 번만** 보이므로 복사해 둡니다.
   > - 발급한 토큰을 위 URL의 `<토큰>` 자리에 넣고 **`Check Repository`**. (토큰이 URL·Coolify 설정에 저장되므로 읽기 전용 권한만 부여합니다.)
 5. **Build Pack: `Dockerfile`**, Branch `main`, Port `3000`.
   ![Coolify 저장소 연결](images/coolify-repo.png)
-6. **Configuration → Domains** 에서 **`Generate Domain`** 클릭 → `https://<레포명>.apps.bokdev.in` 형태로 지정.
+6. **Configuration → Domains** 에서 **`Generate Domain`** 클릭 → `https://<프로젝트명>.apps.bokdev.in` 형태로 지정.
 7. **Environment Variables** 에 `.project-env` 값 등록:
   - **Developer view** 에서 `.project-env` 내용을 그대로 붙여넣으면 일괄 등록됩니다. (`cat ~/projects/myapp/.project-env`)
   - `DATABASE_URL` 은 `%20`·`%3D` 인코딩까지 **그대로** 넣습니다(빼면 DB 연결이 깨집니다).
@@ -306,7 +305,7 @@ Public Repository 방식은 webhook을 걸어야 push가 자동 배포로 이어

 1. **Coolify 앱** → **Configuration → Webhooks** 탭에서, **Gitea** 항목의 **Webhook URL** 과 **Secret** 을 복사합니다. (Secret 칸이 비어 있으면 값을 입력/생성 후 저장)
   ![Coolify Webhook URL·Secret](images/coolify-webhook.png)
-2. **Gitea 레포** → `https://gitea.bokdev.in/playground/myapp` → **Settings → Webhooks → Add Webhook → Gitea** 에 등록:
+2. **Gitea 레포지토리** → `https://gitea.bokdev.in/playground/myapp` → **Settings → Webhooks → Add Webhook → Gitea** 에 등록:
   - **Target URL**: 1번의 Webhook URL
   - **Secret**: 1번의 Secret
   - **Content Type**: `application/json`
@@ -325,14 +324,14 @@ Public Repository 방식은 webhook을 걸어야 push가 자동 배포로 이어

 ```bash
 # Kubero로 배포한 경우 (도메인 .playground.bokdev.in)
-curl https://<레포명>.playground.bokdev.in/healthz   # {"ok":true}
-curl https://<레포명>.playground.bokdev.in/db
-curl https://<레포명>.playground.bokdev.in/s3
+curl https://<프로젝트명>.playground.bokdev.in/healthz   # {"ok":true}
+curl https://<프로젝트명>.playground.bokdev.in/db
+curl https://<프로젝트명>.playground.bokdev.in/s3

 # Coolify로 배포한 경우 (도메인 .apps.bokdev.in)
-curl https://<레포명>.apps.bokdev.in/healthz
-curl https://<레포명>.apps.bokdev.in/db
-curl https://<레포명>.apps.bokdev.in/s3
+curl https://<프로젝트명>.apps.bokdev.in/healthz
+curl https://<프로젝트명>.apps.bokdev.in/db
+curl https://<프로젝트명>.apps.bokdev.in/s3
 ```

 ![배포된 앱](images/08-deployed-app.png)
@@ -371,18 +370,18 @@ curl https://<레포명>.apps.bokdev.in/s3
 - **DB가 비어 있음** → 정상입니다. 빈 전용 스키마가 제공되며 테이블은 직접 생성합니다.
 - **K8s에 직접 접근하고 싶어요** → 직원은 K8s에 직접 접근하지 않습니다. Coder·Gitea·Kubero로 개발·배포가 완결됩니다.

- git 레포 URL vs 배포 URL
+- git 레포지토리 URL vs 배포 URL

   배포 과정에서 나오는 두 주소는 이름이 비슷해 헷갈리기 쉽지만, **서로 완전히 다른 것**입니다.

   | 종류 | 형태 (예시) | 무엇인가 · 브라우저로 열면 | 매뉴얼에서 쓰는 곳 |
   |---|---|---|---|
-   | **git 레포 URL** | `https://gitea.bokdev.in/playground/<레포명>.git` | **내 소스코드가 저장되는 위치**. `git push` 로 코드를 이 주소에 올립니다. (`.git` 을 뗀 주소를 브라우저로 열면 **코드 파일 목록**이 보이며, 실행 중인 앱이 아닙니다.) | [9-2 push](#9-2-push), Coolify의 *Repository URL* 입력([9-3B](#9-3b-coolify에-앱-추가-앱당-1회)) |
-   | **배포 URL** | Kubero `https://<레포명>.playground.bokdev.in`<br>Coolify `https://<레포명>.apps.bokdev.in` | **정식 배포되어 항상 켜져 있는 앱 주소**. 브라우저로 열면 **실제로 실행 중인 앱**이 응답합니다. | [9-4 확인](#9-4-확인) |
+   | **git 레포지토리 URL** | `https://gitea.bokdev.in/playground/<프로젝트명>.git` | **내 소스코드가 저장되는 위치**. `git push` 로 코드를 이 주소에 올립니다. (`.git` 을 뗀 주소를 브라우저로 열면 **코드 파일 목록**이 보이며, 실행 중인 앱이 아닙니다.) | [9-2 push](#9-2-push), Coolify의 *Repository URL* 입력([9-3B](#9-3b-coolify에-앱-추가-앱당-1회)) |
+   | **배포 URL** | Kubero `https://<프로젝트명>.playground.bokdev.in`<br>Coolify `https://<프로젝트명>.apps.bokdev.in` | **정식 배포되어 항상 켜져 있는 앱 주소**. 브라우저로 열면 **실제로 실행 중인 앱**이 응답합니다. | [9-4 확인](#9-4-확인) |

-   > **핵심 구분** — **git 레포 URL = 코드(소스)가 저장된 곳**, **배포 URL = 그 코드가 실제로 실행되어 접속 가능한 앱**.
-   > 절차는 항상 이 순서입니다: **코드를 git 레포 URL로 push → 배포 도구(Kubero/Coolify)가 그 코드로 앱을 빌드 → 배포 URL에 앱이 뜸.**
-   > 즉 push 하는 주소(git 레포)와 접속해서 보는 주소(배포 URL)는 다릅니다.
+   > **핵심 구분** — **git 레포지토리 URL = 코드(소스)가 저장된 곳**, **배포 URL = 그 코드가 실제로 실행되어 접속 가능한 앱**.
+   > 절차는 항상 이 순서입니다: **코드를 git 레포지토리 URL로 push → 배포 도구(Kubero/Coolify)가 그 코드로 앱을 빌드 → 배포 URL에 앱이 뜸.**
+   > 즉 push 하는 주소(git 레포지토리)와 접속해서 보는 주소(배포 URL)는 다릅니다.


 ## 문의