{"id":50324974,"url":"https://github.com/pathcosmos/machine-setting","last_synced_at":"2026-05-29T05:04:28.042Z","repository":{"id":343927468,"uuid":"1172369326","full_name":"pathcosmos/machine-setting","owner":"pathcosmos","description":"Portable AI development environment system","archived":false,"fork":false,"pushed_at":"2026-04-07T07:12:30.000Z","size":250,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T09:13:46.499Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pathcosmos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T08:24:54.000Z","updated_at":"2026-04-07T07:12:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pathcosmos/machine-setting","commit_stats":null,"previous_names":["pathcosmos/machine-setting"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pathcosmos/machine-setting","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fmachine-setting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fmachine-setting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fmachine-setting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fmachine-setting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pathcosmos","download_url":"https://codeload.github.com/pathcosmos/machine-setting/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pathcosmos%2Fmachine-setting/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33637486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T05:04:13.808Z","updated_at":"2026-05-29T05:04:28.017Z","avatar_url":"https://github.com/pathcosmos.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Machine Setting\n\n\u003e 🌐 [English](README_EN.md) | **한국어**\n\nPortable AI development environment system. One command to set up Python + AI/ML packages + optional Node.js/Java on any machine, with automatic GPU/CPU detection and cross-machine sync.\n\n**Supported platforms**: Linux (x86_64, NVIDIA CUDA) + macOS (Apple Silicon M1+, MPS) + Cloud/Container (Docker, K8s, AWS/GCP/Azure)\n**Supported shells**: bash + zsh\n\n---\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [Installation Flow](#installation-flow)\n- [Installed Components](#installed-components)\n- [Daily Usage](#daily-usage)\n- [CLI Options](#cli-options)\n- [Profiles](#profiles)\n- [GPU Support](#gpu-support)\n- [Pre-flight Check](#pre-flight-check)\n- [Reinstallation](#reinstallation)\n- [Uninstall](#uninstall)\n- [Health Check \u0026 Recovery](#health-check--recovery)\n- [Cross-Machine Sync](#cross-machine-sync)\n- [Disk Health \u0026 Monitoring](#disk-health--monitoring)\n- [Shell Integration Details](#shell-integration-details)\n- [Directory Structure](#directory-structure)\n- [State \u0026 Configuration Files](#state--configuration-files)\n- [Troubleshooting](#troubleshooting)\n- [Security](#security)\n\n---\n\n## Quick Start\n\n```bash\n# New machine setup (Linux or macOS)\ngit clone https://github.com/pathcosmos/machine-setting.git ~/machine_setting\ncd ~/machine_setting \u0026\u0026 ./setup.sh\n\n# Cloud/container setup (sudo 없이 user-space만 설치)\n./setup.sh --cloud\n\n# Activate AI environment\naienv\n```\n\n---\n\n## How It Works\n\n### Overview\n\n`setup.sh`는 7단계 파이프라인으로 동작하며, 각 단계는 **체크포인트 시스템**으로 상태가 추적됩니다. 설치가 중간에 실패해도 완료된 단계를 건너뛰고 실패 지점부터 재개할 수 있습니다.\n\n### Execution Flow\n\n```\n./setup.sh 실행\n    │\n    ├─ 1) Pre-flight Check (interactive 모드)\n    │     현재 시스템 상태를 스캔하고 어떤 작업이 필요한지 표시\n    │     사용자가 설치 항목을 선택/해제 가능\n    │\n    ├─ 2) 이전 설치 상태 확인\n    │     ~/.machine_setting/install.state 파일에서 이전 진행 상태 읽기\n    │     → 이전 실패 있으면: Resume / Reset / Cancel 메뉴 표시\n    │     → 모두 완료 상태면: Reinstall / Cancel 메뉴 표시\n    │\n    └─ 3) 7단계 설치 파이프라인 실행\n          각 단계마다 checkpoint 기록 → 실패 시 자동 rollback\n```\n\n### Checkpoint System\n\n모든 설치 상태는 `~/.machine_setting/install.state`에 기록됩니다:\n\n```\nSTAGE_1_HARDWARE=done\nSTAGE_2_NVIDIA=done\nSTAGE_3_PYTHON=done\nSTAGE_4_VENV=in_progress    ← 이 단계에서 실패\nSTAGE_5_NODE=pending\nSTAGE_6_JAVA=pending\nSTAGE_7_SHELL=pending\n```\n\n각 단계가 실패하면:\n1. 해당 단계의 상태를 `failed`로 기록\n2. **자동 롤백** 실행 (해당 단계에서 설치한 것들 제거)\n3. 다음 실행 시 실패 지점부터 재개 가능\n\n---\n\n## Installation Flow\n\n### [1/7] Hardware Detection\n\n시스템 하드웨어를 자동 감지하여 `~/.machine_setting_profile`에 저장합니다.\n\n| 감지 항목 | Linux | macOS |\n|-----------|-------|-------|\n| GPU | `lspci` + `nvidia-smi` (fallback) | `system_profiler` (Apple Silicon) |\n| CUDA 버전 | `nvcc --version` / `nvidia-smi` | N/A (MPS 사용) |\n| CPU/RAM | `/proc/cpuinfo`, `/proc/meminfo` | `sysctl` |\n| NGC 컨테이너 | torch NV 버전 체크 + `/opt/nvidia` 존재 | N/A |\n| Cloud/Container | Docker, K8s, cgroup, 클라우드 VM 벤더, sudo 가용성 | N/A |\n\n\u003e **컨테이너 GPU 감지:** `lspci`가 없는 컨테이너에서도 `nvidia-smi` fallback으로 GPU를 정상 감지합니다.\n\n감지 결과에 따라 최적 프로필이 자동 선택됩니다:\n- Apple Silicon → `mac-apple-silicon`\n- NGC 컨테이너 → `ngc-container`\n- Cloud/Container 환경 → `cloud-server`\n- NVIDIA GPU → `gpu-workstation`\n- RAM ≥ 32GB (GPU 없음) → `cpu-server`\n- RAM ≥ 8GB → `laptop`\n- 그 외 → `minimal`\n\n### [2/7] NVIDIA GPU Stack (Linux 전용)\n\n시스템 레벨 NVIDIA GPU 소프트웨어 스택을 자동으로 설치합니다. `scripts/install-nvidia.sh`가 9개 서브 스테이지를 실행합니다.\n\n**자동 스킵 조건:** 비-Linux OS, NVIDIA GPU 미감지, NGC 컨테이너 (이미 설치됨), `INSTALL_NVIDIA=false`\n\n**GPU 티어 자동 분류:**\n\n| 티어 | GPU 예시 | 동작 |\n|------|----------|------|\n| Consumer | GeForce RTX 3090/4090 | 기본 설치 (드라이버 + CUDA + cuDNN + NCCL) |\n| Professional | RTX A6000, L40 | 기본 설치 |\n| Datacenter | A100, H100, H200, B200 | 기본 + 엔터프라이즈 도구 자동 활성화 |\n\n**설치 구성요소:**\n\n| 구성요소 | 설명 | 설정 |\n|----------|------|------|\n| NVIDIA Driver | `ubuntu-drivers` 자동 추천 또는 수동 버전 지정 | `NVIDIA_DRIVER_VERSION` |\n| CUDA Toolkit | `cuda-toolkit` 메타패키지, `/usr/local/cuda` 심볼릭 링크 | `NVIDIA_CUDA_VERSION` |\n| cuDNN 9.x | DNN 가속 라이브러리 (`cudnn9-cuda-XX`) | 자동 |\n| NCCL | 멀티 GPU 집합 통신 (단일 GPU면 스킵) | 자동 |\n| Container Toolkit | Docker GPU 지원 (Docker 미설치 시 스킵) | `NVIDIA_CONTAINER_TOOLKIT` |\n| Enterprise Tools | DCGM, Fabric Manager, GDS, nvidia-peermem | `NVIDIA_ENTERPRISE` |\n| System Utilities | numactl, hwloc, nvtop, lm-sensors, build-essential, cmake | `NVIDIA_SYSTEM_TOOLS` |\n| Kernel Tuning | sysctl (vm.max_map_count, shmmax 등), memlock limits, CPU governor | `NVIDIA_KERNEL_TUNING` |\n\n**Open vs Proprietary Kernel Modules:**\n- `NVIDIA_OPEN_KERNEL=auto` (기본): Turing+ (RTX 20xx 이상) → open, 구형 → proprietary\n- `NVIDIA_OPEN_KERNEL=true`: 강제 open 커널 모듈\n- `NVIDIA_OPEN_KERNEL=false`: 강제 proprietary 커널 모듈\n\n**Secure Boot:** MOK (Machine Owner Key) 등록 안내가 자동으로 표시됩니다.\n\n**커널 튜닝 상세:**\n- `vm.max_map_count=1048576` (대규모 메모리 매핑)\n- RAM 기반 동적 `shmmax`/`shmall` 계산\n- `memlock unlimited` (GPU 메모리 잠금)\n- TCP 버퍼 최적화 (분산 학습용)\n- CPU governor → performance\n\n### [3/7] Python Setup\n\n[uv](https://github.com/astral-sh/uv)를 통해 Python을 설치합니다 (기본: 3.12).\n\n- uv가 없으면 자동 설치 (`curl -LsSf https://astral.sh/uv/install.sh | sh`)\n- `uv python install 3.12` 으로 관리형 Python 설치\n- 시스템 Python에 영향 없음\n\n### [4/7] AI Environment (Virtual Environment + Packages)\n\nvenv 생성 후 패키지 그룹별로 설치합니다.\n\n**venv 위치 옵션:**\n| 모드 | 경로 | 용도 |\n|------|------|------|\n| global (기본) | `~/ai-env` | 모든 프로젝트에서 공유 |\n| local | `./.venv` | 현재 프로젝트 전용 |\n| custom | 사용자 지정 경로 | 특정 파티션 등 |\n\n**패키지 그룹:**\n| 그룹 | 파일 | 내용 |\n|------|------|------|\n| core | `requirements-core.txt` | transformers, accelerate, peft, wandb, numpy, mlflow, tensorboard, optuna 등 |\n| data | `requirements-data.txt` | pandas, polars, duckdb, SQLAlchemy, psycopg2, pypdf, openpyxl 등 |\n| web | `requirements-web.txt` | fastapi, uvicorn, httpx, gradio, cryptography 등 |\n| gpu | `requirements-gpu.txt` | torch+CUDA, triton, bitsandbytes, deepspeed, vllm, pynvml, nvitop 등 |\n| mps | `requirements-mps.txt` | torch (Apple Silicon MPS 포함) |\n| cpu | `requirements-cpu.txt` | torch CPU-only 빌드 |\n\nGPU/MPS/CPU 패키지는 [1/7]에서 감지된 하드웨어에 따라 자동으로 하나만 선택됩니다.\n\n**디스크 요구사항:** 최소 15GB 여유 공간 권장 (GPU 패키지 포함 시)\n\n#### core — 핵심 AI/ML (`requirements-core.txt`, ~160개)\n\n| 카테고리 | 패키지 | 설명 |\n|----------|--------|------|\n| **LLM Provider** | `anthropic`, `openai`, `google-generativeai` + Google API 7개 | Claude, GPT, Gemini API |\n| **LangChain** | `langchain`, `langchain-community`, `langchain-core`, `langchain-huggingface`, `langgraph`, `langgraph-checkpoint`, `langgraph-prebuilt`, `langgraph-sdk`, `langsmith` | 에이전트/체인/그래프 |\n| **HuggingFace** | `transformers`, `datasets`, `tokenizers`, `huggingface_hub`, `accelerate`, `peft`, `trl`, `sentence-transformers`, `safetensors`, `hf-xet`, `sentencepiece` | 모델 학습/추론/파인튜닝 |\n| **Classical ML** | `scikit-learn`, `scipy`, `xgboost`, `lightgbm`, `numba`, `llvmlite` | 전통 머신러닝 |\n| **Vector/Embedding** | `chromadb`, `faiss-cpu` | 벡터 DB/유사도 검색 |\n| **Visualization** | `matplotlib`, `seaborn`, `contourpy`, `cycler`, `fonttools`, `kiwisolver` | 차트/그래프 |\n| **실험 관리** | `wandb`, `mlflow`, `tensorboard`, `optuna` | 실험 추적/하이퍼파라미터 최적화 |\n| **과학 계산** | `sympy`, `mpmath`, `networkx`, `shapely`, `h5py` | 수학/그래프/지리/HDF5 |\n| **오디오** | `pydub`, `ffmpy` | 오디오 처리/변환 |\n| **Testing** | `pytest`, `pytest-asyncio` | 단위/비동기 테스트 |\n| **NLP/텍스트** | `regex`, `python-bidi`, `Markdown`, `markdown-it-py`, `rich`, `Pygments` | 텍스트 처리/렌더링 |\n| **Utilities** | `pydantic`, `pydantic-settings`, `python-dotenv`, `click`, `typer`, `loguru`, `structlog`, `tqdm`, `coloredlogs`, `humanfriendly`, `prettytable`, `py-cpuinfo`, `tenacity`, `backoff` | 설정/CLI/로깅/재시도 |\n| **Async** | `anyio`, `aiofiles`, `aiohappyeyeballs`, `aiosignal`, `frozenlist`, `multidict`, `yarl` | 비동기 IO |\n| **Serialization** | `typing_extensions`, `marshmallow`, `dataclasses-json`, `jsonschema`, `jsonpatch`, `PyYAML`, `ruamel.yaml` | 스키마/직렬화(YAML 주석 보존) |\n| **gRPC/Protobuf** | `grpcio`, `grpcio-status`, `proto-plus`, `protobuf` | RPC 통신 |\n| **Monitoring** | `opentelemetry-api`, `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-grpc` + 3개, `posthog` | 텔레메트리/분석 |\n| **Infra** | `kubernetes`, `GitPython`, `APScheduler`, `psutil`, `watchdog` | K8s/Git/스케줄링 |\n| **Build** | `packaging`, `setuptools`, `wheel`, `build`, `ninja` | 패키지 빌드 |\n\n#### gpu — NVIDIA GPU 전용 (`requirements-gpu.txt`, ~15개)\n\n| 카테고리 | 패키지 | 설명 |\n|----------|--------|------|\n| **PyTorch** | `torch`, `torchaudio`, `torchvision`, `triton` | CUDA index URL로 GPU 빌드 설치 |\n| **CUDA Bindings** | `cuda-bindings`, `cuda-pathfinder` | CUDA Python 바인딩 |\n| **GPU 가속** | `flash-attn`, `bitsandbytes`, `onnxruntime-gpu` | FlashAttention/양자화/GPU 추론 |\n| **분산 학습** | `deepspeed`, `pytorch-lightning`, `torchmetrics` | 멀티 GPU 학습 |\n| **GPU 모니터링** | `pynvml`, `gpustat`, `nvitop` | GPU 사용량/온도 모니터링 |\n| **추론 최적화** | `vllm`, `optimum` | LLM 고속 서빙/모델 최적화 |\n\n\u003e **참고:** `nvidia-*` 런타임 라이브러리는 `torch` 의존성으로 자동 해소되므로 목록에 미포함. 고정하면 CUDA 버전 간 호환성이 깨질 수 있음.\n\n#### data — 데이터 처리 (`requirements-data.txt`, ~40개)\n\n| 카테고리 | 패키지 | 설명 |\n|----------|--------|------|\n| **DataFrame** | `pandas`, `pyarrow`, `numpy`, `polars`, `duckdb`, `connectorx` | 데이터 분석/쿼리 엔진 |\n| **DB 드라이버** | `SQLAlchemy`, `alembic`, `psycopg2-binary`, `PyMySQL`, `oracledb`, `cx-Oracle`, `clickhouse-connect`, `clickhouse-driver` | PostgreSQL/MySQL/Oracle/ClickHouse |\n| **문서 처리** | `pdfplumber`, `pdfminer.six`, `pypdf`, `pypdfium2`, `python-docx`, `python-pptx`, `openpyxl`, `xlsxwriter`, `lxml` | PDF/Word/Excel/PPT 파싱 |\n| **이미지** | `pillow`, `opencv-python`, `opencv-python-headless`, `scikit-image`, `ImageIO` | 이미지 처리/CV |\n| **OCR** | `easyocr`, `pytesseract` | 광학 문자 인식 |\n| **스크래핑** | `beautifulsoup4` | HTML 파싱/웹 스크래핑 |\n| **통계/설명** | `statsmodels`, `shap` | 통계 모델/설명 가능성 |\n| **직렬화** | `orjson`, `ormsgpack`, `jsonlines`, `ujson` | 고속 JSON/MsgPack |\n| **메시징** | `aiokafka`, `kafka-python`, `paho-mqtt` | Kafka/MQTT 스트리밍 |\n| **클라우드** | `boto3`, `botocore`, `s3transfer` | AWS S3 스토리지 |\n\n선택 설치(필요 시): `paddleocr`, `paddlepaddle`, `paddlex`, `opencv-contrib-python`, `ultralytics` — `requirements-data.txt` 하단 주석 참고.\n\n#### web — 웹/API (`requirements-web.txt`, ~25개)\n\n| 카테고리 | 패키지 | 설명 |\n|----------|--------|------|\n| **프레임워크** | `fastapi`, `starlette`, `uvicorn`, `uvloop`, `Flask`, `Werkzeug`, `gradio`, `gradio_client` | REST API/UI 서버 |\n| **HTTP 클라이언트** | `httpx`, `httpx-sse`, `httpcore`, `requests`, `requests-oauthlib`, `aiohttp` | 동기/비동기 HTTP |\n| **서버 유틸** | `h11`, `httptools`, `websockets`, `websocket-client`, `watchfiles`, `python-multipart` | 고성능 서버/WebSocket |\n| **템플릿** | `Jinja2`, `MarkupSafe`, `itsdangerous` | HTML 렌더링 |\n| **인증/보안** | `PyJWT`, `bcrypt`, `cryptography`, `pyOpenSSL` | JWT/암호화/TLS |\n| **모니터링** | `prometheus_client`, `sentry-sdk` | 메트릭/에러 추적 |\n\n#### cpu — CPU 전용 (`requirements-cpu.txt`, 4개)\n\n| 패키지 | 설명 |\n|--------|------|\n| `torch`, `torchaudio`, `torchvision` | CPU 빌드 (PyTorch CPU index URL) |\n| `onnxruntime` | CPU 추론 엔진 |\n\n#### mps — Apple Silicon (`requirements-mps.txt`, 4개)\n\n| 패키지 | 설명 |\n|--------|------|\n| `torch`, `torchaudio`, `torchvision` | 기본 PyPI 빌드 (MPS 포함) |\n| `onnxruntime` | CPU 추론 엔진 (macOS용 GPU 버전 없음) |\n\n**설치 조합 예시:** GPU 워크스테이션 = `core` + `gpu` + `data` + `web` ≈ **240+개 패키지**\n\n### [5/7] Node.js (선택)\n\nNVM (Node Version Manager)을 설치하고, Node.js LTS를 설치합니다.\n\n- 프로필에 따라 기본 선택/미선택 결정\n- Interactive 모드에서 설치 여부를 물어봄\n- Lazy loading: 셸 시작 시 NVM을 로드하지 않고, `node`/`npm` 최초 실행 시 로드\n\n### [6/7] Java (선택)\n\nSDKMAN을 설치하고, Java 21 (LTS)을 설치합니다.\n\n- 프로필에 따라 기본 선택/미선택 결정\n- Lazy loading: `sdk`/`java` 최초 실행 시 로드\n\n### [7/7] Shell Integration\n\n`.bashrc`와 `.zshrc`에 모듈 소싱 블록을 추가합니다.\n\n```bash\n# \u003e\u003e\u003e machine_setting \u003e\u003e\u003e\n# Auto-source shell modules from machine_setting\nfor f in ~/machine_setting/shell/bashrc.d/[0-9]*.sh; do\n    [ -r \"$f\" ] \u0026\u0026 source \"$f\"\ndone\n# Source machine-local secrets (never committed)\n[ -r \"$HOME/.bashrc.local\" ] \u0026\u0026 source \"$HOME/.bashrc.local\"\n# \u003c\u003c\u003c machine_setting \u003c\u003c\u003c\n```\n\n이 블록은 다음 셸 모듈을 순서대로 로드합니다:\n\n| 파일 | 역할 |\n|------|------|\n| `00-path.sh` | PATH 설정 (CUDA, Homebrew, uv, Maven) |\n| `10-aliases.sh` | 공통 별칭 (아래 표 참조) |\n| `20-env.sh` | 환경변수 설정 |\n| `30-nvm.sh` | NVM lazy loader (`node`/`npm` 최초 실행 시 로드) |\n| `40-sdkman.sh` | SDKMAN lazy loader |\n| `50-ai-env.sh` | `aienv` / `aienv-off` 함수 + 백그라운드 업데이트 체크 |\n\n#### 쉘 별칭 목록 (`10-aliases.sh`)\n\n| 별칭 | 명령 | 용도 |\n|------|------|------|\n| `py` | `python3` | Python 실행 |\n| `pip` | `pip3` | pip 실행 |\n| `ipy` | `ipython` | IPython |\n| `gs` | `git status` | Git 상태 |\n| `gd` | `git diff` | Git 변경사항 |\n| `gl` | `git log --oneline -20` | 최근 커밋 20개 |\n| `gp` | `git pull --rebase` | Git pull |\n| `ms` | `cd ~/machine_setting` | 저장소 이동 |\n| `mss` | `make status` | 동기화 상태 |\n| `msu` | `make update` | 업데이트 |\n| `msp` | `make push` | 푸시 |\n| `gpustat` | `nvidia-smi --query-gpu=...` | GPU 상태 (Linux: nvidia-smi, macOS: ioreg) |\n\n---\n\n## Installed Components\n\n설치 후 시스템에 추가되는 항목 정리:\n\n### Files \u0026 Directories\n\n| 경로 | 설명 | 삭제 대상 |\n|------|------|-----------|\n| `~/machine_setting/` | 이 저장소 자체 | `rm -rf ~/machine_setting` |\n| `~/ai-env/` | Python venv (global 모드) | `make uninstall` |\n| `~/.local/bin/uv` | uv 패키지 매니저 | 수동 삭제 |\n| `~/.local/share/uv/python/` | uv가 관리하는 Python 빌드 | `make uninstall` |\n| `~/.nvm/` | NVM + Node.js | `make uninstall` |\n| `~/.sdkman/` | SDKMAN + Java | `make uninstall` |\n| `~/.machine_setting/` | 설치 상태/체크포인트/백업 | `make uninstall` |\n| `~/.machine_setting_profile` | 하드웨어 감지 결과 | `make uninstall` |\n| `~/.bashrc.local` | 사용자 시크릿 (자동 생성 템플릿) | **절대 삭제 안함** |\n| `~/.zshrc.local` | zsh용 시크릿 (bashrc.local 심볼릭 링크) | **절대 삭제 안함** |\n\n### NVIDIA 시스템 파일 (Stage 2에서 설치)\n\n| 경로 | 설명 | 삭제 대상 |\n|------|------|-----------|\n| NVIDIA driver | `nvidia-driver-XXX` 패키지 | `uninstall --component nvidia` |\n| `/usr/local/cuda` | CUDA Toolkit 심볼릭 링크 | `uninstall --component nvidia` |\n| `cuda-toolkit` | CUDA 개발 도구 | `uninstall --component nvidia` |\n| `cudnn9-cuda-*` | cuDNN 9.x 라이브러리 | `uninstall --component nvidia` |\n| `libnccl2`, `libnccl-dev` | NCCL 멀티 GPU 통신 | `uninstall --component nvidia` |\n| `nvidia-container-toolkit` | Docker GPU 지원 | `uninstall --component nvidia` |\n| `/etc/sysctl.d/99-machine-setting-gpu.conf` | GPU 커널 파라미터 | `uninstall --component nvidia` |\n| `/etc/security/limits.d/99-machine-setting-gpu.conf` | memlock/nproc limits | `uninstall --component nvidia` |\n| numactl, hwloc, nvtop, lm-sensors | 시스템 유틸리티 | 수동 삭제 |\n\n### Shell RC Modifications\n\n`.bashrc`와 `.zshrc`에 마커 블록(`# \u003e\u003e\u003e machine_setting \u003e\u003e\u003e` ~ `# \u003c\u003c\u003c machine_setting \u003c\u003c\u003c`)이 추가됩니다. 삭제 시 이 블록만 제거되며, 사용자의 다른 설정은 보존됩니다.\n\n### Environment Variables (활성화 시)\n\n| 변수 | 값 | 조건 |\n|------|------|------|\n| `PATH` | `~/.local/bin`, CUDA 경로 등 추가 | 항상 |\n| `CUDA_HOME` | `/usr/local/cuda` | Linux + CUDA |\n| `LD_LIBRARY_PATH` | CUDA lib64 추가 | Linux + CUDA |\n| `NVM_DIR` | `~/.nvm` | Node 설치 시 |\n| `NVIDIA_TF32_OVERRIDE` | `1` | `aienv` 활성화 시 (Ampere+ GPU) |\n\n---\n\n## Daily Usage\n\n```bash\naienv                  # Activate venv + background update check\naienv-off              # Deactivate\n\nmake check             # Verify environment (GPU, packages)\nmake push              # Export packages + commit + push to remote\nmake update            # Pull changes + notify if packages changed\nmake status            # Show sync status\nmake export            # Export current venv to requirements files\nmake doctor            # Full health check\nmake recover           # Auto-recover broken components\n```\n\n### 전체 Make 타겟\n\n| 타겟 | 설명 |\n|------|------|\n| `make setup` | 전체 부트스트랩 설치 |\n| `make plan` | Pre-flight check (설치 계획만) |\n| `make preflight` | Pre-flight check 후 설치 |\n| `make dry-run` | 전체 시스템 dry-run 진단 (7단계) |\n| `make check` | AI 환경 검증 (GPU, 패키지) |\n| `make update` | 리모트에서 pull + 변경사항 알림 |\n| `make push` | 패키지 export + commit + push |\n| `make status` | 동기화 상태 확인 |\n| `make export` | venv → requirements 파일 export |\n| `make venv` | venv 생성/업데이트 |\n| `make venv-local` | 프로젝트 로컬 venv 생성 |\n| `make detect` | 하드웨어 감지 실행 |\n| `make secrets` | 시크릿 누출 스캔 |\n| `make doctor` | 건강 체크 |\n| `make recover` | 자동 복구 |\n| `make verify` | 패키지 무결성 검증 |\n| `make uninstall` | 대화형 삭제 |\n| `make uninstall-dry` | 삭제 미리보기 |\n| `make reset` | 상태 초기화 후 처음부터 |\n| `make cloud` | Cloud/container 설치 (user-space only, sudo 불필요) |\n| `make gpu-extras` | GPU 보조만 설치 (시스템 유틸 + 커널 튜닝, sudo). 드라이버/CUDA는 이미 있을 때 사용 |\n| `make gpu-doctor` | GPU 전용 건강 진단 |\n| `make gpu-persist-fix` | GPU 안정성 영구 수정 (sudo 필요) |\n| `make gpu-persist-check` | GPU 안정성 수정 상태 확인 (sudo 불필요) |\n\n### `aienv` 동작 상세\n\n1. `~/ai-env/bin/activate` 실행 (venv 활성화)\n2. `NVIDIA_TF32_OVERRIDE=1` 설정 (Ampere+ GPU에서 FP32 연산 ~2x 가속)\n3. Cloud/container에서 nvcc 없으면 `DS_BUILD_OPS=0` 자동 설정 (DeepSpeed JIT 컴파일 비활성)\n4. **백그라운드 업데이트 체크** 시작:\n   - 24시간마다 `git fetch origin main` 실행\n   - 로컬과 리모트가 다르면 업데이트 알림 출력\n   - 완전히 백그라운드로 실행되어 셸 속도에 영향 없음\n\n### `make check` 출력 예시\n\n```\n=== AI Environment Check ===\n  Venv: /root/ai-env\n  Python: Python 3.12.13\n\n  Installed packages: 379\n\n--- Core Packages ---\n  OK  transformers 4.57.6\n  OK  datasets 4.6.1\n  OK  accelerate 1.12.0\n  ...\n\n--- GPU Stack ---\n  torch 2.10.0+cu128 (CUDA 12.8, 1 GPU(s), NVIDIA H100 PCIe)\n  cuDNN 91002 (enabled=True)\n  NCCL 2.27.5\n\n--- GPU Packages ---\n  bitsandbytes 0.49.2\n  triton 3.6.0\n  vllm 0.17.1\n  deepspeed 0.18.8\n\n--- GPU Functional Test ---\n  matmul (512x512): OK\n  cuDNN conv2d:     OK\n  GPU memory:       39.4 GB\n  Compute cap:      (9, 0)\n\n--- Environment ---\n  Container: yes\n  nvcc: stub (runtime only, no JIT compile)\n  Display: headless (no libGL)\n```\n\n---\n\n## CLI Options\n\n### Interactive (기본)\n\n```bash\n./setup.sh\n```\n\n모든 단계에서 옵션을 물어봅니다 (Python 버전, venv 위치, Node/Java 설치 여부). Pre-flight check가 먼저 실행되어 현재 상태와 필요한 작업을 보여줍니다.\n\n### Non-interactive\n\n```bash\n# 전체 지정\n./setup.sh --python 3.12 --venv global --node --java\n\n# 프로필 사용\n./setup.sh --profile gpu-workstation\n./setup.sh --profile mac-apple-silicon\n\n# 선택적 설치\n./setup.sh --no-node --no-java --venv local\n\n# Custom venv 경로\n./setup.sh --venv /data/ai-env\n```\n\n### Dry-Run 진단\n\n```bash\n# 전체 시스템 dry-run (7개 전 단계 진단)\n./setup.sh --dry-run\nmake dry-run\n\n# 특정 단계만 진단\n./scripts/dry-run.sh --stage nvidia\n./scripts/dry-run.sh --stage python\n\n# 프로필 기반 진단\n./scripts/dry-run.sh --profile gpu-workstation\n\n# JSON 출력 (스크립팅용)\n./scripts/dry-run.sh --json\n```\n\nDry-run은 실제 설치 없이 7개 전 단계를 분석합니다:\n- 현재 설치 상태 및 버전 감지\n- 설치/업그레이드/스킵 액션 플랜\n- 충돌 및 호환성 검사 (CUDA↔PyTorch, Python↔venv 등)\n- 디스크 사용량 및 예상 설치 시간\n- 차단 이슈 발견 시 exit code 1 반환\n\n### Pre-flight \u0026 Planning\n\n```bash\n# 설치 계획만 확인 (실제 설치 안함)\n./setup.sh --plan\nmake plan\n\n# Pre-flight check 후 선택적 설치\n./setup.sh --preflight\nmake preflight\n\n# 직접 실행 (추가 옵션)\n./scripts/preflight.sh --check-only       # 상태 확인만 (= --plan)\n./scripts/preflight.sh --quiet            # 비대화형 (계획 파일 작성 후 종료)\n./scripts/preflight.sh --profile gpu-workstation  # 특정 프로필 기준 검사\n```\n\n### Resume \u0026 Recovery\n\n```bash\n# 이전 실패 지점부터 재개\n./setup.sh --resume\n\n# 상태 초기화 후 처음부터\n./setup.sh --reset\n\n# 특정 단계부터 시작 (이전 단계는 완료 처리)\n./setup.sh --from 4    # Stage 4 (venv)부터\n./setup.sh --from 7    # Stage 7 (shell)만\n\n# 건강 체크\n./setup.sh --doctor\n\n# 자동 복구\n./setup.sh --recover\n```\n\n### 전체 옵션 요약\n\n| Flag | 설명 |\n|------|------|\n| `--python \u003cver\u003e` | Python 버전 (기본: 3.12) |\n| `--venv \u003cmode\u003e` | `global` / `local` / `\u003ccustom-path\u003e` |\n| `--node` / `--no-node` | Node.js 설치/미설치 |\n| `--java` / `--no-java` | Java 설치/미설치 |\n| `--profile \u003cname\u003e` | 프로필 사용 |\n| `--cloud` | Cloud/container 모드 (드라이버/CUDA/커널 튜닝 스킵) |\n| `--dry-run` | 전체 시스템 dry-run 진단 (7단계) |\n| `--plan` | Pre-flight check만 실행 |\n| `--preflight` | Pre-flight check 후 설치 |\n| `--resume` | 실패 지점부터 재개 |\n| `--reset` | 상태 초기화 후 처음부터 |\n| `--from \u003cN\u003e` | Stage N (1-7)부터 시작 |\n| `--doctor` | 건강 체크 |\n| `--recover` | 자동 복구 |\n| `--uninstall` | 삭제 (추가 플래그 가능) |\n| `--gpu-doctor` | GPU 전용 건강 진단 |\n| `--gpu-persist-fix` | GPU 안정성 영구 수정 (sudo 필요) |\n\n---\n\n## Profiles\n\n| Profile | Platform | GPU Backend | NVIDIA Stage | Node | Java | Packages |\n|---------|----------|-------------|-------------|------|------|----------|\n| gpu-enterprise | Linux | CUDA (Enterprise) | Full + DCGM/FM/GDS | No | No | core+data+web+gpu |\n| ngc-container | NGC/Linux | CUDA (NV symlink) | Skip (pre-installed) | No | No | core+data+web+nv-link |\n| gpu-workstation | Linux | CUDA | Full (consumer) | Yes | Yes | core+data+web+gpu |\n| cloud-server | Cloud/Container | CUDA (호스트 제공) | Skip (user-space only) | Yes | Yes | core+data+web+gpu |\n| mac-apple-silicon | macOS | MPS | Skip (N/A) | Yes | No | core+data+web+mps |\n| cpu-server | Linux | None | Skip (no GPU) | Yes | Yes | core+data+web+cpu |\n| laptop | Any | None | Skip (no GPU) | Yes | No | core+data+web+cpu |\n| minimal | Any | None | Skip | No | No | core only |\n\n### Machine-specific 설정\n\n`config/machine.conf`를 만들어 기본 설정을 오버라이드할 수 있습니다 (`.gitignore`에 포함):\n\n```bash\ncp config/machine.conf.example config/machine.conf\n# 편집: Python 버전, Node/Java 설치 여부, 패키지 그룹 등\n```\n\n---\n\n## GPU Support\n\n| Platform | GPU | Backend | 자동 감지 방법 |\n|----------|-----|---------|---------------|\n| NGC container | NVIDIA | CUDA (NV custom build symlink) | torch 버전 체크 |\n| Cloud/Container | NVIDIA | CUDA (호스트 드라이버 사용) | Docker/K8s/VM 벤더 감지 + nvidia-smi |\n| Linux | NVIDIA | CUDA (cu131, cu130, cu126 등) | lspci + nvcc |\n| macOS arm64 | Apple Silicon | MPS (Metal) | uname -m |\n| Any | None | CPU fallback | 자동 |\n\n### NVIDIA System-Level Install (Stage 2)\n\n[2/7] 단계에서 다음 시스템 레벨 NVIDIA 소프트웨어를 자동 설치합니다:\n\n```bash\n# 자동 모드 (기본) — GPU 감지 후 최적 구성 자동 설치\n./setup.sh\n\n# 수동: NVIDIA 스크립트 직접 실행\n./scripts/install-nvidia.sh                    # 전체 자동\n./scripts/install-nvidia.sh --driver-only      # 드라이버만\n./scripts/install-nvidia.sh --no-driver        # 드라이버 제외 (CUDA/cuDNN/NCCL만)\n./scripts/install-nvidia.sh --extras-only      # 보조만 (시스템 유틸 + 커널 튜닝, 드라이버/CUDA 스킵). make gpu-extras와 동일\n./scripts/install-nvidia.sh --enterprise       # 엔터프라이즈 도구 포함\n./scripts/install-nvidia.sh --dry-run          # 설치 미리보기 (심층 진단)\n./scripts/install-nvidia.sh --uninstall        # NVIDIA 스택 전체 제거\n\n# 세부 선택 설치\n./scripts/install-nvidia.sh --no-cuda          # CUDA 제외 (cuDNN/NCCL도 제외)\n./scripts/install-nvidia.sh --no-cudnn         # cuDNN만 제외\n./scripts/install-nvidia.sh --no-nccl          # NCCL만 제외\n./scripts/install-nvidia.sh --no-container-toolkit  # Docker GPU 지원 제외\n./scripts/install-nvidia.sh --no-system-tools  # 시스템 유틸리티 제외\n./scripts/install-nvidia.sh --no-kernel-tuning # 커널/sysctl 최적화 제외\n\n# 버전 지정\n./scripts/install-nvidia.sh --driver-version 570  # 드라이버 버전 지정\n./scripts/install-nvidia.sh --cuda-version 13-0   # CUDA 버전 지정\n./scripts/install-nvidia.sh --open-kernel          # open 커널 모듈 강제\n./scripts/install-nvidia.sh --proprietary          # proprietary 커널 모듈 강제\n```\n\n**NVIDIA 설정 옵션** (`config/default.conf` 또는 `config/machine.conf`):\n\n| 설정 | 기본값 | 설명 |\n|------|--------|------|\n| `INSTALL_NVIDIA` | `true` | NVIDIA 스테이지 전체 활성화/비활성화 |\n| `NVIDIA_DRIVER_VERSION` | `\"\"` (자동) | 드라이버 버전 (비어있으면 추천 버전 자동 선택) |\n| `NVIDIA_CUDA_VERSION` | `\"13-0\"` (CUDA 13.0) | CUDA 버전. 구형 GPU는 machine.conf에서 `\"12-6\"` 등 지정 |\n| `NVIDIA_OPEN_KERNEL` | `auto` | open/proprietary 커널 모듈 선택 |\n| `NVIDIA_ENTERPRISE` | `false` | 엔터프라이즈 도구 (DCGM, FM, GDS, peermem) |\n| `NVIDIA_NO_DRIVER` | `false` | 드라이버 설치 스킵 |\n| `NVIDIA_CONTAINER_TOOLKIT` | `true` | Docker GPU 지원 |\n| `NVIDIA_SYSTEM_TOOLS` | `true` | 빌드 도구, 모니터링 도구 |\n| `NVIDIA_KERNEL_TUNING` | `true` | 커널/sysctl 최적화 |\n\n### CUDA 버전 매칭 (Python 패키지)\n\n감지된 CUDA 버전에 따라 PyTorch index URL이 자동 선택됩니다 (`config/gpu-index-urls.conf`):\n\n```\ncu131=https://download.pytorch.org/whl/cu131\ncu130=https://download.pytorch.org/whl/cu130\ncu126=https://download.pytorch.org/whl/cu126\ncu124=https://download.pytorch.org/whl/cu124\ncu121=https://download.pytorch.org/whl/cu121\ncpu=https://download.pytorch.org/whl/cpu\n```\n\n감지된 CUDA suffix가 목록에 없으면, 가장 가까운 낮은 버전으로 자동 fallback됩니다.\n\n### NGC Container Mode\n\nNGC 컨테이너처럼 시스템에 NV 커스텀 빌드(torch, flash_attn, transformer_engine)가 이미 설치된 환경에서는 PyPI에서 다시 받지 않고 심볼릭 링크로 venv에 연결합니다:\n\n```bash\n# 자동 감지 (NGC 컨테이너면 자동 선택)\n./setup.sh\n\n# 수동 지정\n./setup.sh --profile ngc-container\nscripts/setup-venv.sh --nv-link\n```\n\n**심볼릭 링크 대상 패키지:** torch, torchvision, torchaudio, triton, flash_attn, transformer_engine\n\n동작 방식:\n1. 시스템 site-packages 경로 감지 (예: `/usr/local/lib/python3.12/dist-packages`)\n2. 대상 패키지 디렉토리를 venv의 site-packages에 심볼릭 링크\n3. `.dist-info` 디렉토리도 함께 링크 (pip이 패키지를 인식하도록)\n\n\u003e **Python 버전 불일치 감지:** 시스템 Python(예: 3.10)과 venv Python(예: 3.12)의 버전이 다르면 NV link가 자동으로 스킵되고, GPU 패키지를 pip으로 직접 설치하는 fallback이 동작합니다.\n\n### Cloud/Container Mode\n\nDocker, Kubernetes, 클라우드 VM 등 호스트가 GPU 드라이버를 제공하는 환경에서 user-space 도구만 설치합니다.\n\n```bash\n# 자동 감지 (컨테이너/클라우드 환경이면 자동 활성화)\n./setup.sh\n\n# 명시 지정\n./setup.sh --cloud\nmake cloud\n```\n\n**자동 감지 조건:**\n- `/.dockerenv` 또는 `/run/.containerenv` 존재\n- cgroup에 `docker`/`containerd`/`kubepods` 마커\n- `KUBERNETES_SERVICE_HOST` 환경변수\n- DMI 벤더가 AWS/GCP/Azure/DigitalOcean/Vultr/Oracle\n- sudo 명령이 없거나 권한 없음\n\n**Cloud 모드에서 스킵:**\n- NVIDIA 드라이버/CUDA Toolkit 설치\n- 커널 튜닝 (sysctl, limits)\n- 시스템 패키지 (apt-get)\n\n**Cloud 모드에서 설치:**\n- Hardware Detection (읽기 전용, 호스트 GPU 인식)\n- Python (uv, user-space)\n- AI venv (GPU 패키지 포함 — 호스트 CUDA 런타임 사용)\n- Node.js (nvm), Java (sdkman)\n- Shell integration\n\n**Cloud 환경 추가 대응:**\n- **headless 컨테이너**: `libGL` 없으면 `opencv-python` 대신 `opencv-python-headless`만 설치\n- **nvcc 없는 런타임 컨테이너**: nvcc stub 자동 생성 (DeepSpeed import 호환)\n- **`aienv` 활성화 시**: nvcc 없으면 `DS_BUILD_OPS=0` 자동 설정\n\n### GPU Persistence \u0026 Stability\n\nPCIe 전원 관리로 인한 Xid 79 \"GPU has fallen off the bus\" 문제를 영구적으로 해결합니다.\n\n```bash\n# 상태 확인 (sudo 불필요)\n./scripts/gpu-persist-fix.sh --check\nmake gpu-persist-check\n\n# 영구 수정 적용 (6개 항목)\nsudo ./scripts/gpu-persist-fix.sh\nmake gpu-persist-fix\n\n# 변경 미리보기\nsudo ./scripts/gpu-persist-fix.sh --dry-run\n\n# 변경 되돌리기\nsudo ./scripts/gpu-persist-fix.sh --revert\n```\n\n**적용되는 6가지 수정:**\n\n| # | 항목 | 설명 |\n|---|------|------|\n| 1 | GRUB | PCIe ASPM 비활성화 + GPU 동적 전원 관리 끔 |\n| 2 | udev | NVIDIA GPU PCIe power/control을 'on'으로 강제 |\n| 3 | modprobe | NVreg_DynamicPowerManagement=0x00 설정 |\n| 4 | nvidia-persistenced | GPU persistence daemon 활성화 |\n| 5 | GPU watchdog | 5분마다 GPU 상태 점검 systemd timer |\n| 6 | PCIe power service | 부팅 시 power/control=on 강제 적용 |\n\n\u003e **참고:** PCIe power 설정은 즉시 적용되며, 나머지는 리부트 후 완전 적용됩니다.\n\n---\n\n## Pre-flight Check\n\n`./setup.sh --plan` 또는 `make plan`으로 실제 설치 없이 현재 시스템 상태를 확인합니다.\n\n```\n╔══════════════════════════════════════════════════════╗\n║            Pre-flight System Check                  ║\n╚══════════════════════════════════════════════════════╝\n\n  System:  Ubuntu 22.04.5 LTS / AMD EPYC 7763 (128 cores) / 512GB RAM / 2847GB free\n  GPU:     NVIDIA A100-SXM4-80GB / CUDA 12.6 (cu126)\n  Profile: gpu-workstation\n\n  #  Component            Current Status                 Proposed Action\n  ─────────────────────────────────────────────────────────────────────────────\n  * 1  Hardware Profile     not generated                  → INSTALL\n       Generate ~/.machine_setting_profile\n  * 2  NVIDIA GPU Stack     driver 535 / no CUDA           → INSTALL\n       Install CUDA toolkit, cuDNN, NCCL, system tools\n    3  Python 3.12          3.12.8 installed + uv 0.5.14   (ok)\n  * 4  AI Environment       not created                    → INSTALL\n       Create ~/ai-env + install [core data web + GPU]\n    5  Node.js              v22.12.0 (NVM)                 (ok)\n  * 6  Java 21              not installed                  → INSTALL\n       Install SDKMAN + Java 21\n    7  Shell Integration    configured (.bashrc .zshrc)    (ok)\n```\n\nInteractive 모드에서는 항목별로 토글하여 원하는 것만 설치할 수 있습니다.\n\n---\n\n## Reinstallation\n\n### 전체 재설치\n\n```bash\n# 방법 1: 상태 리셋 후 재설치\n./setup.sh --reset\n\n# 방법 2: make 사용\nmake reset\n```\n\n이 명령은 `~/.machine_setting/install.state` 파일을 초기화하고, 모든 단계를 처음부터 다시 실행합니다. 이미 설치된 컴포넌트(venv, Python 등)는 각 단계에서 \"이미 존재\" 여부를 확인하여 재생성 여부를 물어봅니다.\n\n### 특정 단계만 재설치\n\n```bash\n# Stage 4 (venv)부터 재설치 — Stage 1~3은 건너뜀\n./setup.sh --from 4\n\n# Stage 7 (shell integration)만 재설치\n./setup.sh --from 7\n```\n\n### venv만 재생성\n\n```bash\n# 기존 venv 삭제 후 재생성 (패키지 전체 재설치)\nrm -rf ~/ai-env\nmake venv\n\n# 또는 스크립트 직접 실행 (전체 옵션)\nscripts/setup-venv.sh --global --python 3.12\nscripts/setup-venv.sh --local                  # 프로젝트 로컬 .venv\nscripts/setup-venv.sh --path /custom/path      # 커스텀 경로\nscripts/setup-venv.sh --profile gpu-workstation # 프로필 지정\nscripts/setup-venv.sh --nv-link                # NGC 컨테이너용 (시스템 패키지 심볼릭 링크)\n```\n\n### 패키지만 업데이트\n\n```bash\n# 리모트에서 최신 requirements 가져와서 venv 업데이트\nmake update\n\n# 수동으로 venv에 패키지 재설치\nscripts/setup-venv.sh\n```\n\n---\n\n## Uninstall\n\n### Interactive 모드 (기본)\n\n```bash\nmake uninstall\n# 또는\n./scripts/uninstall.sh\n```\n\n설치된 컴포넌트 목록을 보여주고, 토글 방식으로 삭제할 항목을 선택합니다:\n\n```\n=== Machine Setting Uninstall ===\n\nComponents found:\n  [1] ✓ NVIDIA stack (driver 560.35.03, CUDA, cuDNN, tools)\n  [2] ✓ AI Virtual Environment (~/ai-env, 12G)\n  [3] ✓ Python via uv (1.8G)\n  [4] ✓ NVM + Node.js (287M)\n  [5]   Java/SDKMAN (not installed)\n  [6] ✓ Shell integration (.bashrc .zshrc)\n  [7] ✓ Config \u0026 state files\n\nToggle numbers to select/deselect, 'a' for all, Enter to proceed:\n```\n\n### 전체 삭제\n\n```bash\n# 모든 컴포넌트 삭제 (확인 필요: 'UNINSTALL' 입력)\n./scripts/uninstall.sh --all\n\n# config/state는 유지하고 런타임만 삭제\n./scripts/uninstall.sh --all --keep-config\n```\n\n### 특정 컴포넌트만 삭제\n\n```bash\n# venv와 Node.js만 삭제\n./scripts/uninstall.sh --component venv,node\n\n# NVIDIA 스택만 삭제\n./scripts/uninstall.sh --component nvidia\n\n# 사용 가능한 컴포넌트: nvidia, venv, python, node, java, shell, config\n```\n\n### Dry-run (삭제 미리보기)\n\n```bash\nmake uninstall-dry\n# 또는\n./scripts/uninstall.sh --dry-run\n```\n\n### 완전 삭제\n\nuninstall 후에도 `~/machine_setting` 저장소 자체는 남아있습니다. 완전히 제거하려면:\n\n```bash\n./scripts/uninstall.sh --all\nrm -rf ~/machine_setting\n```\n\n**주의:** `~/.bashrc.local`과 `~/.zshrc.local`은 사용자 시크릿 파일이므로 절대 자동 삭제되지 않습니다.\n\n---\n\n## Health Check \u0026 Recovery\n\n### Doctor (건강 체크)\n\n```bash\nmake doctor\n# 또는\n./scripts/doctor.sh\n```\n\n다음 항목을 점검합니다:\n\n| 체크 항목 | 확인 내용 |\n|-----------|-----------|\n| Disk space | venv 경로에 1GB 이상 여유 |\n| Hardware profile | `~/.machine_setting_profile` 존재 및 유효성 |\n| Cloud environment | Cloud/container 환경 감지 (Docker, K8s, 클라우드 VM, sudo 가용성) |\n| NVIDIA driver | 드라이버 로드 상태, `nvidia-smi` 동작 확인 |\n| CUDA toolkit | `nvcc` 존재 및 버전 (stub vs 실제 nvcc 구분) |\n| cuDNN | dpkg 설치 상태 + **torch.backends.cudnn 런타임 검증** |\n| NCCL | dpkg 설치 상태 + **torch.cuda.nccl 런타임 검증** |\n| GPU kernel tuning | sysctl 파라미터 적용 여부 (cloud에서는 자동 skip) |\n| GPU persistence | gpu-persist-fix 6개 항목 적용 상태 |\n| CPU frequency | CPU 주파수 스로틀링 감지 |\n| Memory | 메모리 여유율 + swap 상태 |\n| Disk SMART health | 디스크 SMART 건강 상태 (smartmontools 필요) |\n| uv | uv 설치 및 버전 |\n| Python | uv로 관리되는 Python 존재 |\n| Virtual environment | venv 디렉토리, bin/python, bin/activate 존재 |\n| Key packages | **26개** 핵심 패키지 import 검증 (torch, transformers, anthropic, fastapi, pandas 등) |\n| GPU packages | **7개** GPU 전용 패키지 (vllm, deepspeed, bitsandbytes, pytorch_lightning 등) |\n| GPU functional | **GPU 연산 테스트** — matmul, cuDNN conv2d, NCCL 가용성 |\n| Node.js | NVM + Node 설치 상태 (설치 선택 시) |\n| Java | SDKMAN + Java 설치 상태 (설치 선택 시) |\n| Shell integration | .bashrc/.zshrc에 마커 블록 존재 |\n| Platform | Xcode CLT (macOS) |\n\n출력 예시 (Cloud/Container 환경):\n\n```\n=== Machine Setting Doctor ===\n\n  [OK]   Disk space (1497GB free)\n  [OK]   Hardware profile\n  [OK]   Cloud environment (container detected)\n  [OK]   NVIDIA driver (535.129.03, NVIDIA H100 PCIe)\n  [WARN] CUDA Toolkit (stub nvcc 12.2 — runtime only, no JIT compile)\n  [OK]   cuDNN (system: 8.9.6, torch: enabled v91002)\n  [OK]   NCCL (system: 2.19.3, torch: 2.27.5)\n  [SKIP] GPU kernel tuning (cloud/container — managed by host)\n  [OK]   GPU persistence (all 6 fixes in place)\n  [OK]   CPU frequency (2899MHz / 3500MHz, 82%)\n  [OK]   Memory (57GB free, 91%)\n  [SKIP] Disk SMART health (smartmontools not installed — apt install smartmontools)\n  [OK]   uv (uv 0.10.10)\n  [OK]   Python (Python 3.12.13)\n  [OK]   Virtual environment (~/ai-env, 379 packages)\n  [OK]   Key packages (OK 26/26)\n  [OK]   GPU packages (OK 7/7)\n  [OK]   GPU functional (OK (NVIDIA H100 PCIe, cuDNN 91002, NCCL ok))\n  [SKIP] Node.js (not installed)\n  [SKIP] Java (not installed)\n  [OK]   Shell integration (.bashrc)\n  [OK]   Platform (Linux)\n\nSummary: 12 ok, 0 failed, 0 warnings, 4 skipped\nAll checks passed!\n```\n\n### Auto-recover (자동 복구)\n\n```bash\n# 모든 실패 항목 자동 복구\nmake recover\n# 또는\n./scripts/doctor.sh --recover\n\n# 특정 컴포넌트만 복구\n./scripts/doctor.sh --recover nvidia\n./scripts/doctor.sh --recover python\n./scripts/doctor.sh --recover venv\n./scripts/doctor.sh --recover shell\n```\n\n사용 가능한 복구 대상: `disk`, `hardware`, `nvidia`, `gpu_persistence`, `uv`, `python`, `venv`, `packages`, `node`, `java`, `shell`, `platform`\n\n각 컴포넌트별 복구 동작:\n\n| 컴포넌트 | 복구 동작 |\n|----------|-----------|\n| hardware | `detect-hardware.sh` 재실행 |\n| nvidia | `install-nvidia.sh` 재실행 (드라이버, CUDA, cuDNN, NCCL) |\n| gpu_persistence | `gpu-persist-fix.sh` 실행 (6개 항목 적용) |\n| uv | uv 재설치 (`curl ... \\| sh`) |\n| python | uv가 없으면 먼저 설치, 그 후 `uv python install` |\n| venv | venv 재생성 + 패키지 재설치 |\n| packages | venv 전체 재설치 (= venv 복구) |\n| node | NVM + Node.js 재설치 |\n| java | SDKMAN + Java 재설치 |\n| shell | `install-shell.sh` 재실행 |\n| platform | macOS: Xcode CLT 안내 |\n| disk | 수동 정리 안내 |\n\n### Package Verification (패키지 무결성 검증)\n\n```bash\nmake verify\n# 또는\n./scripts/doctor.sh --verify-packages\n```\n\nrequirements 파일에 명시된 패키지가 모두 설치되어 있는지 확인합니다:\n\n```\n=== Package Verification ===\n\n  Missing packages (required but not installed):\n    - some-package\n\n  Extra packages (installed but not in requirements): 43\n  (This is normal — they may be transitive dependencies)\n\n  Result: 1 missing package(s)\n  Run './scripts/doctor.sh --recover venv' to install missing packages.\n```\n\n---\n\n## Cross-Machine Sync\n\n여러 머신에서 동일한 패키지 구성을 유지하기 위한 Git 기반 동기화 시스템입니다.\n\n### Push (현재 머신 → 리모트)\n\n```bash\nmake push\n```\n\n동작:\n1. 활성화된 venv에서 현재 패키지 목록을 requirements 파일로 export\n2. 변경사항 `git add -A`\n3. 자동 커밋 메시지 생성: `update: sync from \u003chostname\u003e at \u003ctimestamp\u003e`\n4. `git pull --rebase` 후 `git push`\n\n### Pull (리모트 → 현재 머신)\n\n```bash\nmake update\n```\n\n동작:\n1. `git pull --rebase`\n2. requirements 파일 변경 여부 감지\n3. 변경되었으면 `scripts/setup-venv.sh` 실행 안내 출력\n\n### Status\n\n```bash\nmake status\n```\n\n로컬 변경사항, 리모트 대비 ahead/behind 커밋 수, 마지막 커밋 정보를 보여줍니다.\n\n### Export\n\n```bash\nmake export\n```\n\n현재 venv의 패키지를 카테고리별 requirements 파일로 분류/export합니다:\n- GPU 패키지 → `requirements-gpu.txt`\n- Data 패키지 → `requirements-data.txt`\n- Web 패키지 → `requirements-web.txt`\n- 나머지 → `requirements-core.txt`\n- CPU/MPS 파일은 수동 관리\n\n---\n\n## Disk Health \u0026 Monitoring\n\nNAS/서버 디스크 건강 상태를 점검하는 유틸리티 스크립트 모음입니다. 모든 스크립트는 **읽기 전용** (데이터 변경 없음)이며, `smartmontools`와 `e2fsprogs`가 필요합니다.\n\n```bash\n# SMART 상세 수집 (전 디스크)\nsudo ./scripts/disk-check-smart.sh [출력디렉토리]\n\n# SMART Extended Self-Test 시작 (병렬, 수 시간 소요)\nsudo ./scripts/disk-check-smart-long.sh\n\n# 배드섹터 검사 (병렬 read-only, 수 시간~수십 시간)\nsudo ./scripts/disk-check-badblocks.sh [출력디렉토리]\n\n# 배드섹터 검사 진행률 모니터링\n./scripts/disk-check-progress.sh [출력디렉토리]\nwatch -n 60 ./scripts/disk-check-progress.sh    # 1분마다 자동 갱신\n\n# .badblocks 파일을 512바이트 섹터 구간으로 변환 (파티션 설계용)\n./scripts/disk-badblocks-to-sectors.sh \u003cdisk.badblocks\u003e [섹터여유]\n```\n\n| 스크립트 | 용도 | sudo |\n|----------|------|------|\n| `disk-check-smart.sh` | SMART 상세 수집 + 요약 (Health, Reallocated, Pending) | Yes |\n| `disk-check-smart-long.sh` | SMART Extended Self-Test 병렬 실행 | Yes |\n| `disk-check-badblocks.sh` | 병렬 read-only 배드섹터 검사 | Yes |\n| `disk-check-progress.sh` | 배드섹터 검사 진행률 파싱/표시 | No |\n| `disk-badblocks-to-sectors.sh` | badblocks 결과를 섹터 구간으로 변환 | No |\n\n---\n\n## Shell Integration Details\n\n### Lazy Loading\n\nNVM과 SDKMAN은 **lazy loading** 방식으로 구현되어 셸 시작 시간에 영향을 주지 않습니다:\n\n```bash\n# 30-nvm.sh: node/npm 최초 실행 시에만 NVM 로드\nfor cmd in nvm node npm npx; do\n    eval \"${cmd}() { unset -f nvm node npm npx; _load_nvm; ${cmd} \\\"\\$@\\\"; }\"\ndone\n```\n\n실제 `node --version`을 처음 실행하면 그때 NVM이 로드되고, 이후에는 직접 실행됩니다.\n\n### Background Update Check\n\n`aienv` 실행 시 백그라운드에서 업데이트 체크가 이루어집니다:\n\n1. `~/.last-update-check` 타임스탬프 확인\n2. 24시간 이내면 skip\n3. `git fetch origin main --quiet` (백그라운드)\n4. 로컬 ≠ 리모트이면 업데이트 알림 출력\n\n### Secrets\n\n`~/.bashrc.local`(또는 `~/.zshrc.local`)에 API 키 등 시크릿을 저장합니다:\n\n```bash\n# ~/.bashrc.local (example)\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\nexport OPENAI_API_KEY=\"sk-...\"\nexport WANDB_API_KEY=\"...\"\n```\n\n이 파일은 셸 시작 시 자동으로 source되며, **절대 Git에 커밋되지 않습니다**.\n\n---\n\n## Directory Structure\n\n```\nmachine_setting/\n├── setup.sh              # Single-entry bootstrap (7-stage pipeline)\n├── Makefile              # make setup/update/push/status/doctor/uninstall\n├── config/\n│   ├── default.conf          # Default settings (Python 3.12, Node LTS, Java 21)\n│   ├── machine.conf.example  # Machine-specific override template\n│   └── gpu-index-urls.conf   # PyTorch CUDA index URL mapping\n├── packages/\n│   ├── requirements-core.txt   # Platform-independent AI/ML\n│   ├── requirements-gpu.txt    # NVIDIA CUDA packages\n│   ├── requirements-mps.txt    # Apple Silicon MPS packages\n│   ├── requirements-cpu.txt    # CPU-only fallback\n│   ├── requirements-data.txt   # Data/DB packages\n│   └── requirements-web.txt    # Web/API packages\n├── scripts/\n│   ├── detect-hardware.sh      # GPU/CUDA/MPS/RAM/CPU detection\n│   ├── install-nvidia.sh       # NVIDIA driver/CUDA/cuDNN/NCCL/enterprise tools\n│   ├── install-python.sh       # uv + Python install\n│   ├── setup-venv.sh           # venv creation + package install\n│   ├── install-node.sh         # NVM + Node.js\n│   ├── install-java.sh         # SDKMAN + Java\n│   ├── lib-checkpoint.sh       # Checkpoint/rollback library (7-stage)\n│   ├── dry-run.sh              # 전체 시스템 dry-run 진단 (7단계)\n│   ├── preflight.sh            # Pre-flight system check (NVIDIA 포함)\n│   ├── doctor.sh               # Health check \u0026 recovery (NVIDIA 체크 포함)\n│   ├── uninstall.sh            # Component uninstaller (NVIDIA 포함)\n│   ├── sync.sh                 # Git sync (push/pull/status)\n│   ├── export-packages.sh      # venv → requirements export\n│   ├── check-env.sh            # AI environment verification\n│   ├── check-secrets.sh        # Secret leak scanner\n│   ├── gpu-doctor.sh           # GPU 전용 건강 진단 (6개 섹션 + summary 모드)\n│   ├── gpu-persist-fix.sh      # GPU 안정성 영구 수정 (GRUB, udev, modprobe, persistenced, watchdog, PCIe)\n│   ├── disk-check-smart.sh    # SMART 상세 수집\n│   ├── disk-check-smart-long.sh # SMART Extended Self-Test\n│   ├── disk-check-badblocks.sh  # 병렬 배드섹터 검사\n│   ├── disk-check-progress.sh   # 배드섹터 검사 진행률 모니터\n│   └── disk-badblocks-to-sectors.sh # badblocks→섹터 구간 변환\n├── shell/\n│   ├── install-shell.sh        # Shell RC installer\n│   └── bashrc.d/               # Modular shell config (bash + zsh)\n│       ├── 00-path.sh          # PATH (CUDA, Homebrew, uv)\n│       ├── 10-aliases.sh       # Common aliases\n│       ├── 20-env.sh           # Environment variables\n│       ├── 30-nvm.sh           # NVM lazy loader\n│       ├── 40-sdkman.sh        # SDKMAN lazy loader\n│       ├── 50-ai-env.sh        # aienv/aienv-off + update check\n│       └── 90-local.sh.example # Secrets template\n├── profiles/                   # Pre-configured machine profiles\n│   ├── gpu-enterprise.conf      # A100/H100/B200 + enterprise tools (DCGM, FM)\n│   ├── gpu-workstation.conf\n│   ├── cloud-server.conf\n│   ├── mac-apple-silicon.conf\n│   ├── ngc-container.conf\n│   ├── cpu-server.conf\n│   ├── laptop.conf\n│   └── minimal.conf\n└── docs/                       # System documentation\n    └── package-candidates-analysis.md   # 패키지 후보 분석 (추가 추천/선택/비추천)\n```\n\n---\n\n## State \u0026 Configuration Files\n\n### 런타임 상태 파일 (Git 외부)\n\n| 파일 | 위치 | 용도 |\n|------|------|------|\n| `install.state` | `~/.machine_setting/` | 7단계 설치 진행 상태 (STAGE_1~7) |\n| `backups/` | `~/.machine_setting/backups/` | .bashrc/.zshrc 자동 백업 (셸 통합 설치/업데이트 시 타임스탬프별 생성) |\n| `.machine_setting_profile` | `~/` | 하드웨어 감지 결과 |\n| `.last-update-check` | 저장소 내 | 마지막 업데이트 체크 타임스탬프 |\n| `.preflight_plan` | `env/` | Pre-flight 계획 (임시, 설치 후 삭제) |\n\n### 설정 파일\n\n| 파일 | 위치 | 용도 | Git 포함 |\n|------|------|------|----------|\n| `default.conf` | `config/` | 기본 설정 | Yes |\n| `machine.conf` | `config/` | 머신별 오버라이드 | No (.gitignore) |\n| `gpu-index-urls.conf` | `config/` | CUDA→PyTorch URL 매핑 | Yes |\n| `*.conf` | `profiles/` | 프리셋 프로필 | Yes |\n| `.bashrc.local` | `~/` | 사용자 시크릿 | No |\n\n---\n\n## Troubleshooting\n\n환경 구성 중 문제가 발생하면 [docs/troubleshooting.md](docs/troubleshooting.md)를 참고하세요.\n\n### 빠른 진단\n\n```bash\n# 전체 건강 체크\nmake doctor\n\n# 패키지 무결성 검증\nmake verify\n\n# 시스템 상태 확인 (설치 안함)\nmake plan\n\n# 환경 상세 확인 (GPU, 패키지 버전)\nmake check\n```\n\n### 자주 발생하는 문제\n\n| 증상 | 해결 |\n|------|------|\n| `aienv: command not found` | `source ~/.bashrc` 또는 새 터미널 열기 |\n| `No venv at ~/ai-env` | `make venv` 또는 `./setup.sh --from 4` |\n| GPU가 감지되지 않음 | `make detect` 후 `make doctor` |\n| 패키지 import 실패 | `make verify` → `make recover` |\n| 설치 중간에 실패 | `./setup.sh --resume` |\n| 셸 설정이 깨짐 | `./scripts/doctor.sh --recover shell` (백업에서 복원) |\n| GPU 버스 이탈 (Xid 79) | `sudo ./scripts/gpu-persist-fix.sh` 실행 후 리부트 |\n| GPU 상태 불안정 | `./scripts/gpu-doctor.sh` 로 진단 |\n| `make venv`가 core 단계 직후 즉시 종료 | 옛 6-stage state 파일 잔재. `mv ~/.machine_setting/install.state{,.bak}` 후 재실행 ([7-A](docs/troubleshooting.md#7-a-체크포인트-state-파일-스키마-mismatch--make-venv-즉시-종료-stage-rename-잔재)) |\n| cx-Oracle `pkg_resources` 빌드 실패 | setuptools 70+ 분리 이슈. 자동 fix됨 — 수동시 `uv pip install \"setuptools\u003c70\" wheel` 후 `--no-build-isolation` ([7-B](docs/troubleshooting.md#7-b-cx-oracle-빌드-실패--modulenotfounderror-no-module-named-pkg_resources)) |\n| 검증 단계가 `torch: not installed` 오탐 | bash quote escape 버그. 자동 fix됨 — 실제 설치 여부는 `~/ai-env/bin/python -c 'import torch'`로 확인 ([7-C](docs/troubleshooting.md#7-c-setup-venvsh-검증-단계가-torch-not-installed-false-negative)) |\n\n---\n\n## Security\n\n- Secrets go in `~/.bashrc.local` or `~/.zshrc.local` (never committed)\n- Pre-commit hook blocks AWS keys, GitHub PATs, API keys\n- Repository is **PRIVATE**\n- Run `make secrets` to scan for leaked credentials\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpathcosmos%2Fmachine-setting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpathcosmos%2Fmachine-setting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpathcosmos%2Fmachine-setting/lists"}