playground/sample
121
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
08de45d6f6112da6d7885e73d66df4b7c3030fd5
sample/MANUAL.md
0310700 08de45d6f6 docs: 직원 개발환경 사용 매뉴얼 추가 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-14 17:26:03 +09:00

7.1 KiB
Raw Blame History

개발환경 사용 매뉴얼 (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. 그 안에 starter 폴더가 이미 있습니다 — 표준 프로젝트 골격입니다.

작업 파일은 반드시 /home/coder/projects 아래에 두세요. 이 폴더만 영구 보존됩니다. (워크스페이스를 stop/재시작해도 유지. 그 밖의 위치는 사라질 수 있습니다.)

4. 미리 연결된 것들 (별도 설정 불필요)

새 워크스페이스에는 아래가 자동으로 준비돼 있습니다.

항목 내용
개발 도구 Java(JDK)/Maven, Node 22, Python 3.12, git, psql
컨테이너 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-... 부분을 본인 키로): 
    echo 'sk-여기에-본인-LiteLLM-키' > ~/.config/litellm/key
  3. 적용을 위해 터미널을 새로 엽니다 (또는 source ~/.bashrc).
  4. 확인: 
    echo $ANTHROPIC_BASE_URL   # https://litellm.bok.or.kr 가 나오면 정상
claude                     # Claude Code CLI 실행

키는 본인 워크스페이스 안에만 저장되고, 코드/깃에는 올라가지 않습니다. 게이트웨이 주소(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. 표준 프로젝트로 개발 시작하기 (starter)

~/projects/starter 는 바로 돌려볼 수 있는 Node 예제입니다.

cd ~/projects/starter
npm install
npm run dev            # http://localhost:3000 에서 실행

동작 확인 엔드포인트:

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

MinIO 키는 starter/.env 에 이미 채워져 있습니다. 새 프로젝트는 이 starter를 복사하거나, 같은 구조(Dockerfile + .env)를 따르면 배포까지 매끄럽습니다.

내 DB 직접 접속

psql "$DATABASE_URL"      # 본인 전용 스키마로 바로 접속됨

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

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

cd ~/projects/starter
podman build -t myapp .
podman run --rm -p 3000:3000 --env-file .env -e DATABASE_URL="$DATABASE_URL" myapp
# 또는
podman compose up --build

9. 배포하기 (Coolify)

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

  1. 프로젝트를 Gitea repo에 push (위 6번 인증 후 git push).
  2. Coolify(https://coolify.bokdev.in) 로그인.
  3. 새 리소스 생성 → Git 기반(해당 Gitea repo 연결) → 빌드 방식 Dockerfile.
  4. Coolify의 Environment Variables 에 앱이 쓰는 값 입력
    • DATABASE_URL, S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY 등
    • (로컬 .env에 있던 키들과 동일하게)
  5. 배포(Deploy). 이후 push 하면 자동 재배포됩니다.

컨테이너 포트는 3000 입니다. Coolify에서 도메인/포트를 매핑하세요.

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

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

자주 묻는 것

  • Q. 파일이 사라졌어요 → ~/projects 밖에 저장했을 가능성. 작업물은 항상 ~/projects 아래에.
  • Q. AI 도구가 인증 오류 → ~/.config/litellm/key 에 본인 키가 들어있는지, 터미널을 새로 열었는지 확인 (5번).
  • Q. git push가 인증을 물어봐요 → Gitea Authorize를 한 번도 안 했을 때. 6번 참고.
  • Q. DB가 비어있어요 → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다.
  • Q. K8s(쿠버네티스)는 어떻게 봐요? → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다.

문의: 인프라 담당자