코디세이 교육용 iMac은 학생 계정에 관리자 권한이 없고, 자리도 랜덤 배정에 MaximumUsers=1 정책 때문에 다른 학생이 로그인하는 순간 이 계정의 홈 디렉토리가 통째로 삭제됨 (교육맥 환경 조사는 research/에 있으나 민감정보 포함으로 gitignore 처리, 커밋 안 함). 그래서 "한 번 설치해두는" 방식이 아니라, 로그인할 때마다 이 레포를 클론(또는 git pull)하고 ./bootstrap.sh를 다시 실행하는 것을 전제로 설계함.
교육맥 터미널을 열고(터미널을 연 직후 위치가 어디든 상관없음 — 아래 블록이 항상 ~/Desktop/github/Codyssey-Bootstrap에 클론하고 그 안에서 실행함) 아래 블록을 통째로 붙여넣으면 됨(로그인마다 홈 디렉토리가 삭제되므로 매번 이 블록부터 다시):
mkdir -p ~/Desktop/github && cd ~/Desktop/github
if [ -d Codyssey-Bootstrap ]; then
(cd Codyssey-Bootstrap && git pull)
else
git clone https://github.com/FickleBoBo/Codyssey-Bootstrap.git
fi
cd Codyssey-Bootstrap && ./bootstrap.shpublic repo라 clone에 별도 인증이 필요 없고, bootstrap.sh는 실행 권한이 이미 커밋되어 있어 chmod +x 없이 바로 실행됨. ~/Desktop/github가 없으면 만들고, Codyssey-Bootstrap이 이미 그 안에 있으면(같은 로그인 세션에서 이 블록을 다시 붙여넣은 경우) clone 대신 git pull로 갱신함.
한 번 실행하면 아래를 전부 자동으로 재현함 (전부 홈 디렉토리 스코프, 관리자 권한 불필요):
~/.zshrc,~/.gitconfig,~/.gitignore_global(기존 파일은.bak.<timestamp>로 백업)- oh-my-zsh
- zsh-syntax-highlighting (
~/.zsh에 git clone) - agnoster 테마용 Powerline 폰트 (
~/Library/Fonts) - iTerm2 앱(
/Applications권한 없으면~/Applications) + 프로필 복원(Dynamic Profile) - macOS 키보드 단축키 전체, Dock 자동 가리기/앱 아이콘, 스크롤 방향
- GitHub Push 인증(PAT) — 터미널에서 직접 물어보고 Keychain에 저장
- Claude Code CLI 설치
- VSCode 기본 확장 초기화 (Settings Sync 오염 방지)
멱등적으로 짜여 있어서 여러 번 실행해도 안전함 (이미 되어있는 항목은 스킵).
CLI 도구(node, gh, nvim 등)는 아직 안 넣음 — 교육맥에서 실제로 필요한 게 생기면 그때 이 스크립트를 직접 고쳐서 추가하는 방식으로 감. 참고로 이 기기엔 이미 git/curl/zsh/vim/python3/pip3가 시스템 전역으로 깔려 있고, brew는 조회만 가능(신규 설치는 관리자 소유라 불가).
포함하지 않는 것: Rectangle, SSH 키 생성, macOS 단축어(Shortcuts) 기반 앱 실행 단축키, 구름 입력기(한글 2벌식) 자동 설치. Rectangle·Shortcuts를 뺀 이유는 DECISIONS.md 참고, 구름 입력기는 실기기에서 설치/등록이 제대로 안 되는 문제가 있어 제외(필요하면 로그인 후 직접 설치).
개인 맥 ~/.zshrc에서 터미널 룩앤필과 무관한 항목(rbenv, mysql-client, JAVA_HOME 등 다른 도구 PATH)을 제외하고 남긴 버전. oh-my-zsh 설치 전제, 테마는 agnoster. brew 경로는 있으면 brew --prefix로 동적 감지하지만, 지금 이 교육맥 부트스트랩은 brew를 아예 안 쓰므로 사실상 no-op. zsh-syntax-highlighting은 brew 설치 경로 또는 git clone 경로(~/.zsh/zsh-syntax-highlighting)를 순서대로 찾아서 source. agnoster 테마는 Powerline 폰트가 있어야 기호가 안 깨지는데, 이건 bootstrap.sh가 ~/Library/Fonts에 설치함. ccc는 claude --dangerously-skip-permissions alias.
git config --global core.excludesfile로 지정해서 쓰는 전역 gitignore.
user.name, user.email, core.excludesfile(교육맥 계정에서도 자동으로 $HOME으로 치환되도록 ~/ 상대 표기), init.defaultbranch=main, credential.helper=osxkeychain 포함. ~/.gitconfig로 그대로 복사됨.
credential.helper를 명시한 이유: 이 값은 macOS 어디서나 기본으로 켜져있는 게 아니라서, 이 설정이 없으면 git-credential-osxkeychain 바이너리가 있어도 git credential approve/fill이 저장할 곳이 없어 조용히 아무 일도 안 함(개인 맥은 Homebrew git이 시스템 설정에 자동으로 깔아줘서 이 값 없이도 동작했음). 7단계 PAT 자동화가 정상 동작하려면 반드시 필요(근거로 들었던 환경 설명을 한 번 정정한 적 있음 — DECISIONS.md 참고).
defaults export com.apple.symbolichotkeys로 개인 맥에서 직접 설정한 커스텀 키보드 단축키 전체(35개 키)를 통째로 export 해둔 파일 — 창 타일링(Option+화살표, Ctrl+Option+U/I/J/K, 아래 창 타일링 단축키 섹션 참고)은 그중 8개(240~247)뿐이고, 나머지는 Mission Control/스크린샷/입력 소스 전환 등 개인 맥에서 따로 커스텀했던 단축키들임. defaults import는 이 도메인을 통째로 덮어쓰므로, 복원 시 창 타일링뿐 아니라 이 35개 전부가 개인 맥과 동일하게 맞춰짐(의도된 동작 — 교육맥에도 개인 맥 단축키 세팅을 그대로 가져와 쓰는 것이 목적). 복원:
defaults import com.apple.symbolichotkeys macos/com.apple.symbolichotkeys.plist로그아웃 후 재로그인해야 완전히 반영될 수 있음.
bootstrap.sh가 아래도 같이 적용함 (개별 defaults write라 별도 plist 파일 없음):
- Dock 자동 가리기/보기:
defaults write com.apple.dock autohide -bool true - Dock 앱 아이콘: 아래 별도 섹션 참고
- 스크롤 방향(자연스러운 스크롤 끔):
defaults write -g com.apple.swipescrolldirection -bool false
창 타일링 단축키는 여기 없음 — 위 macos/com.apple.symbolichotkeys.plist import에 포함되어 함께 복원됨(아래 창 타일링 단축키 섹션 참고).
교육맥 기본으로 붙어있는 Dock 항목(Launchpad, Safari, Mail 등 시스템 앱들, 나중에 손으로 추가한 것 포함)은 그대로 두고, 크롬 / iTerm2 / VSCode / OrbStack / Discord 5개만 맨 뒤에 이 순서로 고정함. 5개 다 이 교육맥 이미지에 이미 설치되어 있다는 전제이고(설치까지 자동화하진 않음), 없는 앱은 조용히 스킵함. iTerm2 경로는 5단계에서 계산한 $APP_DIR(/Applications 또는 ~/Applications)를 그대로 재사용.
멱등성 처리: 재실행할 때마다 이 5개 이름과 일치하는 기존 항목을 먼저 지우고 다시 맨 뒤에 붙이는 방식이라 여러 번 돌려도 중복이 안 쌓임(그 외 항목의 순서/구성은 절대 안 건드림). 이름 비교 시 unquote가 필요한 이유: Dock에 한 번 반영되고 나면 macOS가 경로를 file:///Applications/Google%20Chrome.app/처럼 URL 인코딩해서 저장하므로, 그대로 비교하면 매번 다른 문자열로 보여서 매 실행마다 새로 추가되어 중복이 쌓임.
Rectangle 대신 macOS 15(Sequoia) 내장 Window Tiling(Window > Move & Resize 메뉴)에 단축키를 걸어서 씀(관리자 권한 불필요 — Rectangle을 안 쓰는 이유는 DECISIONS.md 참고):
- 절반:
Option+←/→/↑/↓ - 사분할(모서리):
Ctrl+Option+U(좌상단)/I(우상단)/J(좌하단)/K(우하단)
구현 방식: System Settings > Keyboard Shortcuts > Window 패널에서 GUI로 직접 등록한 뒤 defaults export com.apple.symbolichotkeys로 그 결과를 macos/com.apple.symbolichotkeys.plist에 통째로 캡처해서 씀. 이 패널은 macOS 윈도우 서버가 직접 처리하기 때문에 앱이 자체 메뉴를 어떻게 구성했든 상관없이 크롬을 포함한 모든 앱에서 동작함. 내부 ID 번호(AppleSymbolicHotKeys의 240~247)는 macOS 15.7.4에서 실기기로 직접 확인한 값이고, 코드에서 이 번호를 직접 다루지는 않음 — GUI에서 설정한 결과를 그대로 export한 파일을 defaults import로 재생만 하므로 macOS 버전이 바뀌어 번호가 달라져도 다시 캡처만 하면 됨.
iTerm2 앱 전역 설정(com.googlecode.iterm2 도메인 전체)을 defaults import로 덮어쓰지 않음 — 그 도메인엔 색상/폰트 말고도 AI 기능 API 설정, 설치 ID처럼 이 맥에만 의미있는 값이 섞여 있어서, 프로필 데이터(New Bookmarks)만 뽑아 iTerm2 Dynamic Profile JSON 형식으로 저장함. bootstrap.sh가 ~/Library/Application Support/iTerm2/DynamicProfiles/에 복사하면 목록에 뜨는 것 자체는 iTerm2 재시작 없이 바로 반영됨.
다만 이것만으론 Cmd+N 새 창이 이 프로필을 자동으로 쓰지 않음. iTerm2는 새 창에 어떤 프로필을 쓸지 별도의 Default Bookmark Guid 포인터로 관리하는데, Dynamic Profile을 추가하는 것과 그 포인터를 바꾸는 건 별개 동작이라, 포인터가 iTerm2 설치 시 자동 생성된 공장 기본 프로필을 계속 가리키고 있으면 색/폰트가 하나도 안 바뀐 것처럼 보임(Hotkey Window는 프로필 자체에 단축키가 내장돼 있어 이 포인터와 무관하게 동작하므로 정상으로 보이는 것뿐). 그래서 bootstrap.sh가 JSON에서 Default 프로필의 Guid를 읽어 defaults write com.googlecode.iterm2 "Default Bookmark Guid" -string <guid>로 이 키 하나만 갱신함(도메인 전체를 안 건드리는 원칙은 유지) — iTerm2를 껐다 켜야 새 창부터 반영됨.
포함된 프로필 2개:
Default— 색상/폰트(Fira Mono for Powerline)Hotkey Window—Ctrl+````(백틱)으로 여는 Quake 스타일 드롭다운 터미널. 개인 맥에서 쓰는 것과 동일한 iTerm2 내장 기능이라 외부 도구 없이 그대로 이전됨.
이 레포에는 SSH/PAT 등 어떤 인증정보도 포함하지 않음(보안상 금지). bootstrap.sh 7단계가 터미널에서 직접 GitHub 아이디/PAT를 물어보고(read -s로 화면에 안 찍힘) git credential approve로 macOS Keychain에 저장함 — 레포나 디스크의 다른 어떤 파일에도 값이 남지 않음. 이미 Keychain에 저장돼 있으면(같은 로그인 세션 내 재실행 등) 자동으로 스킵.
이미 저장돼 있는지 체크할 때 GIT_TERMINAL_PROMPT=0을 반드시 붙여서 씀 — 이게 없으면 git credential fill이 캐시가 없을 때 터미널에서 직접 Username/Password를 대화형으로 되물어보고, 그 입력값이 체크 결과에 섞여 들어가 저장 단계를 잘못 건너뛸 수 있음(과거 버그 경위는 DECISIONS.md 참고).
PAT가 없다면 GitHub → Settings → Developer settings → Fine-grained tokens에서 새로 발급해야 함. 아래 하나라도 빠지면 push가 403으로 거부됨(계정 자체엔 push 권한이 있어도 무관):
- Repository access: "Public repositories"(읽기 전용)가 아니라 "Only select repositories"(이 레포 선택) 또는 "All repositories"
- Permissions → Repository permissions → Contents: 기본값 "Read-only"가 아니라 "Read and write"
SSH 방식을 쓰고 싶다면 ssh-keygen -t ed25519 -C "yukmw0704@gmail.com" 후 cat ~/.ssh/id_ed25519.pub을 GitHub → Settings → SSH and GPG keys에 등록하면 되지만, 초기화가 잦은 환경이라 매번 새 키를 재등록해야 해서 PAT 쪽을 권장함.
bootstrap.sh 8단계가 공식 네이티브 설치 스크립트로 Claude Code CLI를 설치함:
curl -fsSL https://claude.ai/install.sh | bash관리자 권한도 Node.js/npm도 필요 없음 — ~/.local/bin/claude에 설치되고, 이후 백그라운드에서 알아서 자동 업데이트됨. dotfiles/.zshrc 맨 위에 이미 $HOME/.local/bin이 PATH에 들어가 있어서 설치 스크립트만 돌리면 바로 claude 명령을 쓸 수 있음. 로그인(계정 인증)은 최초 실행 시 claude 명령을 치고 브라우저 프롬프트를 따라가면 됨 — 이 부분은 자동화 대상이 아님(Anthropic 계정 로그인은 매번 사람이 직접 해야 함). 이미 설치돼 있으면 스킵.
이 계정은 root 소유 LaunchAgent(com.codyssey.vscode.setup, 로그인 시 실행 후 10초 대기)가 ~/.vscode가 없을 때만 확장 5종(ms-python.python, ms-python.vscode-pylance, eamodio.gitlens, ms-azuretools.vscode-docker, MS-CEINTL.vscode-language-pack-ko)을 자동 설치함(스크립트 원문은 research/에서 확인, 공개 레포엔 미포함). settings.json/keybindings.json은 이 데몬이 건드리지 않고 완전 기본값으로 남아있는 것도 함께 확인함 — 그래서 초기화 대상은 확장 폴더(~/.vscode)뿐임.
이 상태 그대로 GitHub/Microsoft 계정으로 Settings Sync를 켜고 "병합(merge)"을 선택하면 이 5개 확장이 내 클라우드 프로필에 영구적으로 섞여 들어가 개인 맥까지 오염될 수 있음. 그래서 bootstrap.sh 9단계가 Sync 로그인 전에 ~/.vscode를 비움(rm이 아니라 다른 dotfiles와 동일하게 .bak.<timestamp>로 백업). 그다음 VSCode를 열고 직접 로그인해서 Settings Sync를 켜면 내 프로필만 그대로 내려받힘.
두 가지 안전장치:
- 타이밍: 위 LaunchAgent가 설치를 끝내기 전에 먼저 비우면 데몬이 뒤늦게 다시 깔아버릴 수 있어서,
~/.vscode가 생길 때까지 최대 15초 대기한 뒤 비움(9단계는 앞선 네트워크 단계들 뒤라 실제로 기다리는 경우는 거의 없음). - 재실행 안전성: 같은 로그인 세션에서
bootstrap.sh를 재실행할 때(이미 Settings Sync로 로그인해서 내 확장이 깔린 뒤) 또 지워버리지 않도록, 한 번 비운 뒤엔~/.codyssey_vscode_reset_done마커 파일로 스킵함. 다음 로그인엔 홈 디렉토리 자체가 삭제되므로 마커도 같이 사라져 자연스럽게 다시 초기화됨.