> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 개발 환경 설정

이 문서는 **Windows / macOS / Ubuntu 24.04** 기준으로 개발 환경을 구성하는 시작점입니다.
운영체제별 설치 문서로 바로 이동하기 전에, 전체 순서와 완료 기준을 먼저 정리합니다.

## 이 페이지에서 하는 일

* 운영체제별 설치 경로를 선택합니다.
* 공통 필수 도구(`git`, `vscode`, `nodejs`, `uv`) 설치 순서를 확인합니다.
* GPU 사용 여부에 따라 추가 설치 경로를 분기합니다.
* 설치가 끝났는지 빠르게 검증하는 명령어를 실행합니다.

## 1) 운영체제 경로 선택

<CardGroup cols={3}>
  <Card title="Windows 개발 환경" icon="windows" href="/setup/windows/index">
    WSL 2 기반 개발 환경, NVIDIA/CUDA, Python, Docker, Ollama
  </Card>

  <Card title="macOS 개발 환경" icon="apple" href="/setup/macos/index">
    Homebrew 기반 개발 환경, Python, MPS, Rancher Desktop, Ollama
  </Card>

  <Card title="Ubuntu 24.04 개발 환경" icon="linux" href="/setup/ubuntu/index">
    apt 기반 개발 환경, NVIDIA/CUDA, Python, Docker, Ollama
  </Card>
</CardGroup>

## 2) 권장 설치 순서

<Steps>
  <Step title="기본 도구 설치">
    `git`, `vscode`, `nodejs`, `uv`를 먼저 설치합니다.
  </Step>

  <Step title="GPU 경로 분기">
    GPU를 사용할 때만 NVIDIA 드라이버, CUDA, cuDNN, PyTorch CUDA를 설치합니다.
  </Step>

  <Step title="AI 도구 설치">
    로컬 실습 도구(`ollama`, 컨테이너 런타임)를 설치합니다.
  </Step>

  <Step title="프로젝트 환경 분리">
    실습 목적별 Python 환경은 `UV Env`에서 별도 생성합니다.
  </Step>
</Steps>

## 3) OS별 최소 완료 기준

| OS           | 확인 명령어            | 기대 결과                          |
| ------------ | ----------------- | ------------------------------ |
| Windows      | `wsl --status`    | WSL 상태가 정상 출력                  |
| macOS        | `xcode-select -p` | Command Line Tools 경로 출력       |
| Ubuntu 24.04 | `lsb_release -a`  | `Description: Ubuntu 24.04` 확인 |
| 공통           | `git --version`   | 버전 문자열 출력                      |
| 공통           | `node --version`  | 버전 문자열 출력                      |
| 공통           | `uv --version`    | 버전 문자열 출력                      |

## 4) GPU 사용 시 추가 체크

* Windows/Ubuntu에서는 `nvidia-smi`로 드라이버 인식 여부를 먼저 확인합니다.
* CUDA를 설치한 뒤에는 프레임워크(PyTorch)에서 GPU 장치 인식까지 확인합니다.
* GPU를 사용하지 않는 경우 이 단계를 건너뛰고 CPU 경로로 진행해도 됩니다.

## 5) 프로젝트 환경 분리(권장)

<CardGroup cols={2}>
  <Card title="UV 프로젝트 환경" icon="boxes-stacked" href="/setup/uv-env">
    도메인별 Python 환경을 분리하고 재현 가능한 형태로 관리합니다.
  </Card>

  <Card title="IT Essentials" icon="book-open" href="/it-essentials">
    운영체제, 네트워크, 배포, 보안 등 공통 기반을 함께 학습합니다.
  </Card>
</CardGroup>

<Tip>
  팀 온보딩은 `OS 환경 구성 → UV Env 생성 → 실습 탭 이동` 순서로 진행하면 가장 안정적입니다.
</Tip>

## 설치 점검 체크리스트

* [ ] 운영체제별 시작 문서에서 사전 준비 조건을 확인했습니다.
* [ ] 기본 도구(`git`, `vscode`, `nodejs`, `uv`) 설치를 완료했습니다.
* [ ] GPU 사용 시 드라이버/CUDA 경로까지 완료했습니다.
* [ ] 터미널에서 버전 확인 명령어로 설치 상태를 검증했습니다.
* [ ] 다음 실습을 위한 `UV Env`를 준비했습니다.

## 자주 막히는 지점

1. 명령어가 인식되지 않으면 터미널을 다시 열고 PATH 반영 여부를 먼저 확인합니다.
2. 버전 불일치가 있으면 기존 설치를 정리한 뒤 권장 버전으로 다시 맞춥니다.
3. GPU 인식 실패는 드라이버 → CUDA → 프레임워크 순서로 역추적합니다.
4. 설치 후 동작이 불안정하면 재부팅 후 동일 명령으로 재검증합니다.

## 다음 문서

<CardGroup cols={3}>
  <Card title="Windows 개발 환경" icon="windows" href="/setup/windows/index">
    Windows 경로로 바로 진행합니다.
  </Card>

  <Card title="macOS 개발 환경" icon="apple" href="/setup/macos/index">
    macOS 경로로 바로 진행합니다.
  </Card>

  <Card title="Ubuntu 24.04 개발 환경" icon="linux" href="/setup/ubuntu/index">
    Ubuntu 경로로 바로 진행합니다.
  </Card>
</CardGroup>