playground/sample
121
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
573609cf72269ad7d7e6977a59a9752e02d593a2
sample/MANUAL.md
infra 573609cf72 docs: 개발 앱 미리보기(subdomain) 섹션 추가 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-14 23:39:13 +09:00

11 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. 그 안에 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"      # 본인 전용 스키마로 바로 접속됨

7-1. 개발 중인 앱 미리보기 (브라우저에서 열기)

npm run dev 로 띄운 앱(예: :3000)을 브라우저로 보려면 — 워크스페이스는 사내 클러스터 안에 있어 localhost:3000 으로는 바로 안 열립니다. 아래 방법으로 임시 미리보기 URL 을 받으세요.

VS Code 의 PORTS 패널 (가장 쉬움)

  1. 터미널에서 앱 실행: cd ~/projects/myapp && npm run dev
  2. VS Code 하단 PORTS 탭 → Forward a Port → 포트 번호(3000) 입력 (앱이 뜨면 자동으로 감지해 알림이 뜨기도 합니다)
  3. 포워딩된 포트 옆 🌐 (Open in Browser) 클릭 → 새 탭에 앱이 열립니다.

열리는 주소는 https://<...>.coder.bokdev.in 형태의 본인 전용 임시 URL 입니다(사내 정식 TLS 적용). 본인만 접근 가능하며, 워크스페이스를 끄면 사라집니다. 운영 배포가 아니라 미리보기용입니다. (정식 서비스 배포는 9번 Coolify 참고.)

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/스토리지/배포는 위 도구들로 충분합니다.

문의: 인프라 담당자