sample/MANUAL.md

개발환경 사용 매뉴얼 (Coder)

사내 개발은 Coder(웹 기반 개발 워크스페이스)에서 합니다. 브라우저만 있으면 됩니다. DB·MinIO·AI(LiteLLM)·Git(Gitea)·배포(Coolify)가 미리 연결돼 있어, 로그인 후 바로 코딩할 수 있습니다.

---

0. 준비물

• 사내망에서 접속 가능한 브라우저 (Chrome/Edge 권장)
• 본인 사번

---

1. Coder 로그인

1. 브라우저에서 https://coder.bokdev.in 접속
2. 로그인
   • Username: 본인 사번 (예: 0310700)
   • Password: bok1234!! + 본인 사번 (예: bok1234!!0310700)

   • 최초 로그인 후 비밀번호를 바꾸는 것을 권장합니다. (우측 상단 계정 메뉴 → Account)

---

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

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

1. 로그인하면 Workspaces 화면. Create Workspace 클릭 (또는 Templates → aidev 선택)
2. 설정값 입력
   • Name: 워크스페이스 이름 (예: ws-aidev-<사번> 또는 자유롭게)
   • CPU / Memory / Home disk size: 기본값(2 Core / 4 GiB / 10 GiB)으로 두면 됩니다. 필요하면 나중에 늘릴 수 있습니다.
3. Create Workspace 클릭
4. 워크스페이스가 빌드됩니다 (처음엔 이미지 다운로드로 2~5분 걸릴 수 있습니다. 기다리세요).
   • 상태가 Running 이 되면 준비 완료.

한 번 만들면 계속 재사용합니다. 다음부터는 만들 필요 없이 Start 만 누르면 됩니다.

---

3. VS Code 열기

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

1. 터미널 열기: VS Code 상단 메뉴 Terminal → New Terminal
2. 아래 명령을 입력하고, 안내가 나오면 발급받은 본인 키(sk-...)를 붙여넣습니다:

   update-litellm-key
   

   LiteLLM virtual key 입력 (sk-...): sk-여기에-본인-키-붙여넣기
   키 갱신 완료 (len=25). 현재 터미널에 즉시 적용됨.
   

   update-litellm-key 는 키를 파일에 저장하고 현재 터미널에 바로 적용합니다. 터미널을 새로 열거나 source 할 필요가 없습니다. 키를 바꿀 때도 같은 명령을 다시 쓰면 됩니다.

3. 확인:

   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

키는 본인 워크스페이스 안에만 저장되고, 코드/깃에는 올라가지 않습니다. 게이트웨이 주소(https://litellm.bok.or.kr)는 이미 설정돼 있으니 건드릴 필요 없습니다.

---

6. Git(Gitea) 사용 — 최초 1회 승인

코드 저장소는 사내 Gitea(https://gitea.bokdev.in)입니다. 토큰 입력 없이 자동 인증됩니다.

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

예:

cd ~/projects
git clone https://gitea.bokdev.in/<org>/<repo>.git

---

7. 새 프로젝트 시작하기 (sample 복사)

~/projects/sample 은 바로 돌려볼 수 있는 Node 예제이며 읽기 전용 참조입니다. 직접 고치지 말고, new-project 명령으로 복사해서 본인 프로젝트를 시작하세요.

new-project myapp       # sample 을 ~/projects/myapp 으로 복사 + .project-env(DB/S3) 자동생성
cd ~/projects/myapp     # 폴더에 들어오면 .project-env 가 자동 적용됨($DATABASE_URL 등 사용 가능)
npm install
npm run dev             # http://localhost:3000 에서 실행

동작 확인 엔드포인트:

• GET /healthz — 살아있는지
• GET /db — 내 DB(Postgres) 연결 확인
• GET /s3 — MinIO(파일 저장소) 연결 확인

.project-env 가 그 프로젝트의 설정 파일입니다 (DB·S3). 값을 바꾸려면 이 파일 한 곳만 고치면 됩니다. 프로젝트 폴더에 들어가면(cd) 자동으로 환경변수에 반영됩니다. (git에는 올라가지 않습니다) LiteLLM 키만은 프로젝트가 아니라 워크스페이스 전체 공용이라 ~/.env(5번 update-litellm-key)에서 관리합니다.

내 DB 직접 접속

cd ~/projects/myapp       # 프로젝트 폴더에서 (그래야 .project-env 가 로드됨)
psql "$DATABASE_URL"      # 본인 전용 스키마로 바로 접속됨

---

8. 컨테이너로 실행 (podman)

로컬에서 컨테이너로 돌려보기 (실제 런타임은 rootless podman, docker 명령도 동일하게 동작):

cd ~/projects/myapp
podman build -t myapp .
podman run --rm -p 3000:3000 --env-file .project-env myapp
# 또는
podman compose up --build

빌드/실행에 필요한 권한은 워크스페이스에 이미 설정돼 있습니다(별도 설정 불필요). 컨테이너가 뜬 뒤 접속 확인은 127.0.0.1 로 하세요(localhost 가 간혹 안 잡힙니다):

curl 127.0.0.1:3000/healthz     # {"ok":true}
curl 127.0.0.1:3000/db          # DB 연결 확인

---

9. 배포하기 (Coolify)

운영 배포는 Coolify가 담당합니다. 흐름은 "Gitea에 push → Coolify가 Dockerfile로 자동 빌드·배포" 입니다.

1. 프로젝트를 Gitea repo에 push (위 6번 인증 후 git push).
2. Coolify(https://coolify.bokdev.in) 로그인.
3. 새 리소스 생성 → Git 기반(Public) → 빌드 방식 Dockerfile.
   • Repository URL 은 반드시 전체 주소로 입력: https://gitea.bokdev.in/<org>/<repo>.git (<org>/<repo> 처럼 줄여 쓰면 clone 이 실패합니다.)
   • Branch: main, Port: 3000
4. Coolify의 Environment Variables 에 앱이 쓰는 값 입력 (앱마다 최초 1회만, 이후 배포엔 유지됨)
   • DATABASE_URL, S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, PORT
   • 워크스페이스 .project-env 의 값을 그대로 복사해 넣으면 됩니다 (DB host 도 동일).

     DATABASE_URL=postgresql://emp_<사번>:<pw>@10.200.0.152:5432/appdb?options=-c search_path=emp_<사번>
     

5. 배포(Deploy). 이후 git push 하면 자동 재배포됩니다.

• 설정(.project-env)은 git 에 올라가지 않으므로, 배포 환경값은 Coolify Environment Variables 에 입력합니다(개발=.project-env, 배포=Coolify, 값은 동일).
• 컨테이너 포트는 3000. Coolify에서 도메인/포트를 매핑하세요.

---

10. 워크스페이스 켜고 끄기

• 그만 쓸 때: Coder 워크스페이스 화면 → Stop (자원 절약. 파일은 보존됩니다.)
• 다시 쓸 때: Start (수십 초 내 기동)
• 업데이트 안내가 뜨면(Update 버튼): 눌러서 최신 환경으로 갱신하세요. ~/projects 파일은 유지됩니다.

---

자주 묻는 것

• Q. 파일이 사라졌어요 → ~/projects 밖에 저장했을 가능성. 작업물은 항상 ~/projects 아래에.
• Q. AI 도구가 인증 오류(401) → update-litellm-key 를 다시 실행해 본인 키를 입력하세요 (5번). 키가 sk- 로 시작하는지 확인.
• Q. AI 도구가 Invalid model 오류(400) → 인증은 됐지만 모델명이 게이트웨이에 없는 경우. 5번 표의 기본 모델명을 쓰세요.
• Q. $DATABASE_URL 이 비어있어요 → 프로젝트 폴더 안에서 실행했는지 확인하세요. .project-env 는 그 폴더에 cd 해야 적용됩니다(7번).
• Q. sample 을 고쳤는데 git pull 이 안 돼요 → sample 은 참조용(읽기 전용)입니다. new-project <이름> 으로 복사한 폴더에서 작업하세요(7번).
• Q. git push가 인증을 물어봐요 → Gitea Authorize를 한 번도 안 했을 때. 6번 참고.
• Q. Coolify 배포가 does not appear to be a git repository 로 실패해요 → Repository URL 을 전체 주소(https://gitea.bokdev.in/...git)로 넣었는지 확인하세요(9번).
• Q. 배포한 앱에서 DB 연결이 안 돼요(/db 500) → Coolify Env 의 DATABASE_URL host 가 10.200.0.152 인지 확인하세요. 컨테이너명/내부 DNS 는 배포 환경에선 안 됩니다(9번).
• Q. DB가 비어있어요 → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다.
• Q. K8s(쿠버네티스)는 어떻게 봐요? → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다.

---

문의: 인프라 담당자