Files

infra 14161ba496 docs: VS Code로 폴더 여는 법 + 터미널 열기 + npm install 강조 (초보용)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-14 23:52:04 +09:00

14 KiB

Raw Blame History

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

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

0. 준비물

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

1. Coder 로그인

브라우저에서 https://coder.bokdev.in 접속
로그인
- Username: 본인 사번 (예: 0310700)
- Password: bok1234!! + 본인 사번 (예: bok1234!!0310700)
- 최초 로그인 후 비밀번호를 바꾸는 것을 권장합니다. (우측 상단 계정 메뉴 → Account)

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

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

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

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

3. VS Code 열기

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

터미널 열기: VS Code 상단 메뉴 Terminal → New Terminal
아래 명령을 입력하고, 안내가 나오면 발급받은 본인 키(sk-...)를 붙여넣습니다:
```
update-litellm-key
```
```
LiteLLM virtual key 입력 (sk-...): sk-여기에-본인-키-붙여넣기
키 갱신 완료 (len=25). 현재 터미널에 즉시 적용됨.
```
update-litellm-key 는 키를 파일에 저장하고 현재 터미널에 바로 적용합니다. 터미널을 새로 열거나 source 할 필요가 없습니다. 키를 바꿀 때도 같은 명령을 다시 쓰면 됩니다.

확인:

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)입니다. 토큰 입력 없이 자동 인증됩니다.

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

예:

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

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

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

(1) 터미널 열기 — VS Code 상단 메뉴 Terminal → New Terminal (화면 아래쪽에 터미널 창이 뜹니다)

(2) 프로젝트 만들기 — 터미널에 입력:

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)에서:

npm install             # 처음 1회: 필요한 라이브러리 설치 (이걸 안 하면 실행이 실패합니다)
npm run dev             # 앱 실행 (미리보기는 7-2 참고)

동작 확인 엔드포인트:

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

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

내 DB 직접 접속

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

7-1. 프로젝트를 Gitea(git)에 올리기

new-project 로 만든 폴더는 git 저장소가 아직 아닙니다(.git 없음). 아래처럼 올립니다.

1) Gitea에 빈 저장소 만들기

https://gitea.bokdev.in → 우측 상단 + → New Repository
Repository Name 입력(예: myapp)
README/.gitignore/License 는 체크하지 마세요(빈 저장소여야 충돌이 없습니다) → Create
생성되면 주소가 나옵니다: https://gitea.bokdev.in/<본인사번>/myapp.git

2) 워크스페이스 터미널에서 올리기

cd ~/projects/myapp
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://gitea.bokdev.in/<본인사번>/myapp.git
git push -u origin main

인증은 자동입니다(6번 Gitea 승인을 한 번 했다면). 처음이면 승인 화면이 한 번 뜹니다.
이후 수정한 뒤에는 git add . && git commit -m "..." && git push 만 반복하면 됩니다.

순서는 상관없습니다. 코드를 먼저 만들고(권장) 나중에 저장소를 만들어도 되고, 저장소를 먼저 만들어도 됩니다. git push 시점에 Gitea 저장소만 있으면 됩니다. .project-env 는 git에 올라가지 않습니다(DB·S3 자격증명 보호 — 정상). git status 에 안 보여도 맞습니다. 배포 시엔 그 값을 Coolify에 따로 넣습니다(9번).

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

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

먼저 7번처럼 new-project <이름> 으로 만든 본인 프로젝트 폴더가 있어야 합니다. (myapp 은 예시 이름입니다. new-project 로 만들지 않은 폴더는 없습니다.)

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

터미널에서 본인 프로젝트 폴더로 가서 앱 실행:

cd ~/projects/<본인이 만든 이름>      # 예: cd ~/projects/myapp
npm run dev

VS Code 하단 PORTS 탭 → Forward a Port → 포트 번호(3000) 입력 (앱이 뜨면 자동으로 감지해 알림이 뜨기도 합니다)
포워딩된 포트 옆 🌐 (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로 자동 빌드·배포" 입니다.

프로젝트를 Gitea repo에 push (위 6번 인증 후 git push).
Coolify(https://coolify.bokdev.in) 로그인.
새 리소스 생성 → Git 기반(Public) → 빌드 방식 Dockerfile.
- Repository URL 은 반드시 전체 주소로 입력: https://gitea.bokdev.in/<org>/<repo>.git (<org>/<repo> 처럼 줄여 쓰면 clone 이 실패합니다.)
- Branch: main, Port: 3000
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_<사번>
```
배포(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/스토리지/배포는 위 도구들로 충분합니다.

문의: 인프라 담당자

14 KiB Raw Blame History