Thiết lập macOS đầy đủ cho máy phát triển

Hướng dẫn đi từ máy Mac mới đến môi trường làm việc có shell, Git, runtime, container, cloud, IaC, IDE và quy trình sao lưu. Các bước nền tảng áp dụng cho Apple Silicon và Intel; chọn thêm nhóm công cụ theo dự án. Hoàn thành setup nghĩa là mở Terminal mới vẫn tìm thấy đúng công cụ, chạy được dự án mẫu và khôi phục được dữ liệu quan trọng.

1. Kiểm tra máy và cập nhật hệ điều hành

Mở Terminal rồi kiểm tra phiên bản macOS và kiến trúc đang chạy:

sw_vers
uname -m
system_profiler SPHardwareDataType
softwareupdate --list

arm64 là Apple Silicon, x86_64 thường là Intel. Terminal chạy qua Rosetta trên Apple Silicon cũng có thể báo x86_64; đối chiếu chip trong About This Mac. Dùng terminal native để tránh cài lẫn hai bộ Homebrew và dependency khác kiến trúc.

Trong System Settings, hoàn tất các bước sau:

• General → Software Update: cài bản cập nhật phù hợp và bật cập nhật bảo mật tự động.
• Privacy & Security: bật FileVault, giữ Gatekeeper và System Integrity Protection hoạt động.
• Network → Firewall: bật tường lửa và xem lại ứng dụng được phép nhận kết nối.
• Lock Screen: yêu cầu mật khẩu khi mở khóa; Touch ID bổ sung cho mật khẩu mạnh.
• Trackpad: bật tap to click, nhấp phụ bằng hai ngón và điều chỉnh tốc độ con trỏ.
• Accessibility → Pointer Control: chọn kéo bằng ba ngón nếu phù hợp thao tác của bạn.
• Keyboard: thêm bộ gõ cần dùng, kiểm tra phím tắt và repeat rate.
• Finder: hiển thị phần mở rộng tên file, dùng Cmd + Shift + . khi cần xem file ẩn.

Lưu công việc trước khi cài bản cập nhật cần khởi động lại. Xem lịch sử bằng:

softwareupdate --history

2. Command Line Tools và Homebrew

Cài công cụ biên dịch

xcode-select --install

Hoàn tất hộp thoại cài đặt, sau đó kiểm tra:

xcode-select -p
clang --version
git --version

Command Line Tools đủ cho đa số công cụ CLI. Cài Xcode đầy đủ từ App Store khi phát triển ứng dụng iOS/macOS cần SDK, simulator hoặc giao diện Xcode.

Cài Homebrew theo đúng kiến trúc

Tải script từ dự án Homebrew, xem nội dung rồi chạy:

curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh -o /tmp/homebrew-install.sh
less /tmp/homebrew-install.sh
/bin/bash /tmp/homebrew-install.sh

Thêm một dòng tương ứng vào ~/.zprofile, theo hướng dẫn mà installer in ra:

Mở Terminal mới hoặc nạp lại cấu hình rồi kiểm tra:

source ~/.zprofile
brew --version
brew --prefix
brew doctor

Homebrew dùng prefix riêng cho hai kiến trúc. Khả năng hỗ trợ macOS và Intel thay đổi theo thời gian; kiểm tra máy thuộc nhóm hỗ trợ nào trước khi dùng phiên bản cũ. Nguồn: Homebrew Installation.

Cài bộ CLI nền tảng

brew install git gh just jq tree ripgrep bat eza fzf ncdu neovim gnupg uv pre-commit

macOS có nhiều tiện ích BSD, khác một số tùy chọn GNU/Linux. Khi script cần GNU Make, cài brew install make và gọi gmake; khi cần GNU coreutils, cài brew install coreutils và dùng tên có tiền tố g. Không thay hàng loạt công cụ hệ thống trước khi biết script cần gì.

3. Quản lý bộ phần mềm bằng Brewfile

Tạo ~/Brewfile.dev để quản lý danh mục phần mềm của bạn. Bắt đầu với bộ tối thiểu dưới đây, rồi bổ sung runtime, database, công cụ cloud và IDE theo nhu cầu. Đọc tùy chọn của từng gói trước khi cài, đặc biệt nếu gói có thể bật hoặc restart service.

brew "git"
brew "gh"
brew "just"
brew "jq"
brew "ripgrep"
brew "uv"
brew "podman"
brew "podman-compose"
cask "visual-studio-code"
cask "font-meslo-lg-nerd-font"

brew bundle list --file="$HOME/Brewfile.dev"
brew bundle install --file="$HOME/Brewfile.dev"
brew bundle check --file="$HOME/Brewfile.dev"

brew bundle install có thể nâng cấp gói đã có. Dùng --no-upgrade nếu chỉ muốn bổ sung gói còn thiếu; Brewfile không khóa mọi dependency tại một phiên bản tuyệt đối. Nguồn: Homebrew Bundle.

4. Terminal, font và Zsh

Terminal mặc định đủ để bắt đầu. Cài iTerm2 nếu cần profile, chia pane hoặc cấu hình phím chi tiết; chọn Nerd Font nếu prompt dùng icon:

brew install --cask iterm2 font-meslo-lg-nerd-font
zsh --version

Trong profile của terminal và font terminal của IDE, chọn Meslo Nerd Font đã cài. Nếu icon thành ô vuông, kiểm tra font ở cả hai nơi. Nguồn: cask Meslo Nerd Font.

Phân vai các file shell

macOS đã dùng Zsh mặc định. Nếu cần bản Homebrew, cài brew install zsh, đăng ký đúng đường dẫn từ brew --prefix trong /etc/shells rồi mới dùng chsh. Có thể tiếp tục dùng /bin/zsh nếu chưa có yêu cầu cụ thể.

Oh My Zsh và plugin

Cài theo hướng dẫn Oh My Zsh. Trước khi thay cấu hình đang có, lưu một bản riêng để có thể khôi phục. Bộ plugin gợi ý trong ~/.zshrc:

plugins=(git brew python pip rust uv aws kubectl)
source "$HOME/.oh-my-zsh/oh-my-zsh.sh"
eval "$(fzf --zsh)"

zsh-autosuggestions, zsh-completions, zsh-syntax-highlighting và fzf-tab là plugin bổ sung, cần cài từ repository của chính plugin trước khi thêm vào danh sách. Kiểm tra hướng dẫn tương thích của từng plugin khi thay đổi thứ tự hoặc kết hợp với highlighting; mở shell mới để kiểm completion sau mỗi thay đổi.

Alias tối thiểu, thêm vào ~/.zshrc:

alias ll='eza -lah'
alias lt='eza --tree --level=2'
alias c='clear'
alias k='kubectl'

Mở shell mới để kiểm tra. Trong Zsh, không dùng path hoặc status làm tên biến riêng: chúng là tham số đặc biệt của shell. Cấu hình tương tác không nên là điều kiện để recipe trong CI chạy được.

5. SSH, Git và xác thực

Tạo khóa SSH

mkdir -p ~/.ssh
chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "dev-workstation" -f ~/.ssh/id_ed25519_dev
ssh-add --apple-use-keychain ~/.ssh/id_ed25519_dev
pbcopy < ~/.ssh/id_ed25519_dev.pub

Đặt passphrase khi tạo khóa và chỉ đưa public key .pub lên dịch vụ Git. Comment dev-workstation là nhãn nhận diện key, có thể thay bằng nhãn của bạn. Với cờ --apple-use-keychain, dùng /usr/bin/ssh-add nếu phiên bản OpenSSH cài thêm không hỗ trợ cờ này. Nguồn: tạo SSH key trên macOS.

Ví dụ ~/.ssh/config cho một tài khoản Git:

Host github-dev
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_dev
    IdentitiesOnly yes
    AddKeysToAgent yes
    UseKeychain yes

chmod 600 ~/.ssh/config ~/.ssh/id_ed25519_dev
ssh -T git@github-dev

Đối chiếu host fingerprint với tài liệu dịch vụ khi kết nối lần đầu. Nếu dùng nhiều tài khoản, mỗi tài khoản có key và Host alias riêng, và URL clone phải dùng đúng alias. Không thêm kết quả ssh-keyscan vào known_hosts mà chưa kiểm fingerprint.

Cấu hình Git

git config --global user.name "TEN_HIEN_THI"
git config --global user.email "DIA_CHI_COMMIT"
git config --global init.defaultBranch main
git config --global pull.ff only
git config --global core.editor "vim"
git config --global --list --show-origin

Thay TEN_HIEN_THI và DIA_CHI_COMMIT bằng danh tính commit của bạn trước khi chạy. Nếu dùng VS Code, thay editor bằng code --wait sau khi lệnh code hoạt động. Dùng cấu hình local trong từng repository khi cần danh tính khác. Với GitHub CLI:

gh auth login
gh auth status

Nếu muốn diff bằng GUI, cài Meld và cấu hình git difftool. Dùng git difftool khi cần GUI và git diff khi cần kết quả văn bản trong terminal, SSH hoặc CI.

6. Runtime và môi trường theo dự án

Chỉ cài runtime dùng trong công việc. Ưu tiên file pin version của repository thay vì thay phiên bản global theo từng dự án; một runtime không nên được nhiều manager cùng quản lý.

Python với uv

uv --version
uv python install 3.14
uv python list

Trong thư mục dự án Python đã có pyproject.toml và lockfile:

uv sync
uv run python --version
uv run pytest

Với dự án mới, tạo uv venv --python 3.14 rồi cài dependency vào môi trường đó. CLI độc lập có thể cài bằng uv tool install; không cần sudo pip hoặc sửa Python hệ thống. Nguồn: quản lý Python bằng uv.

Node.js và package manager

Upstream nvm không hỗ trợ cách cài qua Homebrew. Với máy mới, cài nvm theo hướng dẫn upstream và thêm các dòng nạp NVM_DIR/nvm.sh do installer đề xuất vào ~/.zshrc. Sau khi mở shell mới:

nvm install --lts
nvm use --lts
node --version
npm --version

Trong dự án đã có .nvmrc, dùng nvm install rồi nvm use. Chọn npm, pnpm hoặc Yarn theo trường packageManager và lockfile; không tạo thêm lockfile của manager khác. Corepack không có sẵn trong mọi bản Node, nên theo hướng dẫn của manager được dự án chọn. Nguồn: nvm upstream.

Rust

Cài toolchain qua rustup, sau đó:

source "$HOME/.cargo/env"
rustup component add rustfmt clippy
rustc --version
cargo --version

Giữ ~/.cargo/bin trong PATH. Trong dự án dùng rust-toolchain.toml, rustup chọn toolchain tương ứng; kiểm tra bằng rustup show trước khi build.

Go, Java, PHP và Dart

Ví dụ dùng JDK Homebrew trực tiếp mà không thay symlink toàn hệ thống, thêm vào shell:

export JAVA_HOME="$(brew --prefix openjdk@17)/libexec/openjdk.jdk/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"

Khi nhiều dự án cần các phiên bản Python/PHP/JDK khác nhau, tách môi trường theo dự án. Các PHP legacy từ tap ngoài cần được xem như môi trường tương thích riêng; không đưa chúng thành bản mặc định cho máy mới. Khi dùng nhiều PHP, kiểm tra command -v php và PATH thay vì chạy brew link --overwrite --force theo thói quen.

7. Container và máy ảo Linux

Container Linux trên macOS chạy trong VM. Hướng dẫn này dùng Podman CLI trực tiếp; cài Podman Desktop chỉ khi cần GUI quản lý.

brew install podman podman-compose vfkit
podman machine list

Nếu chưa có VM, khởi tạo rồi chạy:

podman machine init --provider applehv --cpus 4 --memory 4096
podman machine start
podman info
podman run --rm quay.io/podman/hello
podman-compose --version

applehv là provider hợp lệ trên macOS; tên vz không phải giá trị của cờ provider. Chọn CPU/RAM để vẫn còn tài nguyên cho IDE và hệ điều hành. Kiểm tra podman machine init --help của bản đang dùng trước khi thêm cờ mount. Nguồn: Podman machine init.

VM đã tạo dùng disk riêng chứa image và volume. Các thao tác thông thường:

podman machine list
podman system connection list
podman ps -a
podman volume ls
podman system df

Nếu VM báo đang chạy nhưng engine hỏng sau sleep/wake, dừng và khởi động lại:

podman machine stop
podman machine start
podman info

Khởi động lại giữ disk của VM. podman machine rm xóa dữ liệu VM; chỉ dùng khi đã xuất database/volume cần giữ. Không alias docker=podman toàn shell: dự án cần Docker API, Compose hay driver Kubernetes có thể có yêu cầu riêng. Trên Apple Silicon, ưu tiên image ARM64 hoặc multi-arch; dùng image AMD64 qua giả lập có thể chậm và không tương thích mọi workload.

8. Database và công cụ GUI

Chọn chạy database bằng container theo Compose của dự án hoặc cài service Homebrew. Tránh chạy hai instance dùng cùng port. Với cài đặt native:

brew install postgresql@17 mysql
brew services list

Chỉ bật service cần dùng, ví dụ PostgreSQL:

brew services start postgresql@17
"$(brew --prefix postgresql@17)/bin/psql" --version
brew services info postgresql@17

Trước nâng major version, đọc quy trình migrate và tạo backup; đổi binary không tự đảm bảo data directory cũ tương thích. Với Redis, chọn image/container của dự án hoặc phương thức cài từ nhà cung cấp; RedisInsight là GUI quan sát và quản lý kết nối.

Cài một editor chính trước; mở dự án và kiểm tra formatter, interpreter, terminal, extension cần dùng. Charles và IDE thương mại cần giấy phép hợp lệ; chứng chỉ proxy chỉ cài khi cần, chỉ giữ phạm vi tin cậy phù hợp. Nếu ứng dụng bị Gatekeeper chặn, kiểm nguồn tải/chữ ký và làm theo hướng dẫn nhà cung cấp thay vì xóa quarantine hàng loạt hoặc tắt Gatekeeper.

9. Cloud, SSH tunnel và công cụ hỗ trợ

AWS

brew install awscli
aws --version
aws configure sso --profile dev
aws sso login --profile dev

Wizard yêu cầu thông tin IAM Identity Center do quản trị viên cung cấp. Dùng profile riêng cho mỗi môi trường, kiểm tra đúng profile trước khi chạy lệnh thay đổi tài nguyên. Giữ cấu hình/credential trong kho riêng của máy, không chép token, account ID hoặc SSO URL nội bộ vào wiki. Với xác thực SSO, ưu tiên phiên ngắn hạn thay access key tĩnh. Nguồn: cấu hình AWS CLI SSO.

Khi cần Systems Manager:

brew install --cask session-manager-plugin
session-manager-plugin --version

Nguồn: Session Manager Plugin cask. AWS SAM CLI dùng cho build/test ứng dụng serverless; chọn installer macOS đúng kiến trúc theo hướng dẫn SAM. LocalStack phục vụ giả lập API AWS trong local dev, cài theo hướng dẫn dự án và kiểm khả năng tương thích container runtime trước khi sử dụng.

Google Cloud và cloud CLI khác

brew install --cask gcloud-cli
gcloud --version
gcloud init

Tên cask hiện hành là gcloud-cli. Với ứng dụng dùng Application Default Credentials, làm theo cơ chế đăng nhập của dự án; không mặc định đổi credential global cho mọi dự án. Các CLI cloud khác cũng cần kiểm tra account, region/project và quyền trước khi dùng. Nguồn: Google Cloud CLI cask.

Tunnel và tiện ích

brew install autossh cloudflared rclone

• autossh giám sát kết nối SSH dài; tunnel qua bastion cần quyền và hostname do quản trị viên cung cấp. Dùng SSH config riêng của máy, không ghi endpoint nội bộ lên wiki.
• cloudflared phục vụ tunnel/Zero Trust theo cấu hình dự án; chọn phương án xác thực phù hợp, giữ token ngoài source.
• rclone đồng bộ lưu trữ và backup; kiểm tra đích và thử --dry-run trước tác vụ sync vì sync có thể xóa file ở đích.
• aws-vault là lựa chọn lưu credential trong keychain nếu tổ chức dùng cơ chế này.
• CLI AI như Claude, Gemini hoặc Kiro là nhóm tùy chọn. Dùng installer chính thức, đăng nhập riêng và rà soát quyền đọc file, hook cùng lịch sử phiên trước khi dùng.

10. IaC, Kubernetes và tự động hóa

OpenTofu và Terragrunt bằng tenv

brew install tofuutils/tap/tenv
tenv tofu install latest
tenv tofu use latest
tenv tg install latest
tenv tg use latest
tofu --version
terragrunt --version

Lệnh trên tạo baseline cho máy mới. Với dự án hiện hữu, dùng version đã pin qua .opentofu-version, .terragrunt-version hoặc constraint của repository. tenv quản lý phiên bản và proxy cho các CLI; kiểm tra command -v tofu nếu có bản cài khác che mất proxy. Đặt export TG_TF_PATH=tofu khi cấu hình Terragrunt của dự án cần chỉ rõ executable. Nguồn: tenv.

Phân biệt kiểm tra local với plan cần credential/backend từ xa; xem plan trước khi áp dụng. Terraform/OpenTofu state có thể chứa dữ liệu nhạy cảm, cần backend và quyền truy cập thích hợp.

Kubernetes

brew install kubectl helm k9s minikube
kubectl version --client
helm version
k9s version
minikube version

Trước kết nối cluster, chọn kubeconfig và context chính xác. kubectl nên nằm trong khoảng version được cluster hỗ trợ; với cluster local, chọn driver tương thích với runtime đang dùng theo tài liệu Minikube, không mặc định mọi driver Podman hoạt động giống Docker. Nguồn: cài kubectl macOS.

kubectl config get-contexts
kubectl config current-context

Có thể thêm source <(kubectl completion zsh) vào .zshrc nếu chưa có plugin completion tương ứng. Helm quản lý release; k9s hỗ trợ quan sát/tác nghiệp và cũng phải được mở ở đúng context.

Ansible và build tools

brew install ansible cmake
ansible --version
cmake --version

Ansible chạy ở máy điều khiển để cấu hình host qua SSH. Cài collection theo requirements.yml của dự án, chọn inventory đúng rồi kiểm bằng --check --diff nếu module hỗ trợ. Dự án cần Temporal có thể cài CLI từ Brewfile và dùng dev server theo hướng dẫn dự án; apache-arrow, imagemagick, ffmpeg và percona-toolkit bổ sung cho xử lý dữ liệu/media hoặc vận hành database, không phải điều kiện boot máy.

11. Tiện ích shell và chẩn đoán hệ thống

Dùng công cụ có sẵn trên macOS hoặc đã cài ở các bước trước để kiểm tra máy. Khi thêm plugin shell, đọc mã và kiểm dependency trước khi nạp. Không sao chép history, SSH config, credential hoặc .zshrc chứa cấu hình riêng sang máy khác.

Completion và thao tác thường ngày

Với Makefile thật, dùng command make; GNU Make Homebrew gọi gmake. Completion là tiện ích shell, không thay thế just --list và just --show khi kiểm lệnh sắp chạy.

Chẩn đoán và dữ liệu nhạy cảm

system_profiler, ioreg, sysctl và smartctl cung cấp các góc nhìn khác nhau; macOS không dùng dữ liệu SMBIOS như PC. Trên Apple Silicon, một số trang SMART không được hỗ trợ, nên xem chỉ số đọc được thay vì kết luận ổ hỏng chỉ từ exit code. Các helper phân tích dung lượng xem cả thư mục ẩn; dataset/video ở ngoài các cache quen thuộc cũng có thể là nguyên nhân đầy disk.

Cập nhật và dọn dẹp

• Kiểm cập nhật macOS trong System Settings; dùng brew update, brew outdated rồi brew upgrade cho gói đã rà soát. Trả lời prompt sudo thật khi cask yêu cầu.
• Xem trước phạm vi với brew cleanup --dry-run; backup dữ liệu trước khi dọn cache hoặc xóa bản runtime/IDE extension cũ.
• History có thể chứa dữ liệu riêng tư; không công khai hoặc sao chép sang máy khác. Giữ note và dữ liệu cần thiết khi dọn transcript/log của công cụ AI.
• Khởi động lại Podman VM để xử lý lỗi kết nối trước khi cân nhắc reset. Reset có thể xóa VM và dữ liệu; chỉ dùng sau khi đã backup image/volume cần giữ.

Audit bảo mật endpoint

Rà soát lớp bảo vệ macOS, DNS/kết nối, file khả nghi, executable đặc quyền, dependency và cấu hình AI/IDE. Không coi một lần kiểm tra sạch là chứng minh máy không bị xâm nhập:

• Giữ SIP, Gatekeeper và firewall hoạt động; xem security agent nếu máy được quản lý.
• Đối chiếu IoC với nguồn cảnh báo hiện hành, vì danh sách nhúng trong script có thể cũ.
• Kiểm tra hook, task tự chạy, lệnh tải/chạy mã từ mạng và thay đổi ngoài dự kiến.
• Rà soát executable đặc quyền ở vị trí người dùng và dependency tải gần đây.
• Nếu phát hiện nghi vấn, giữ log, ngừng tác vụ có credential và chuyển sang quy trình ứng phó; không chạy payload hoặc xóa dấu vết để thử xem cảnh báo biến mất không.

12. Sao lưu và khả năng khôi phục

Thiết lập Time Machine trên ổ ngoài, chọn mã hóa backup và chạy bản sao lưu đầu tiên. Thử khôi phục một file mẫu; bản sao lưu chưa kiểm restore chưa chứng minh được khả năng phục hồi. iCloud đồng bộ hữu ích nhưng không thay mọi chức năng backup. Nguồn: Time Machine.

Giữ secret/key trong backup mã hóa hoặc kho credential riêng. Chụp danh mục phần mềm vào file mới, không ghi đè Brewfile đã chọn lọc:

brew bundle dump --file="$HOME/Brewfile.snapshot"

Khôi phục theo thứ tự: cập nhật OS → CLT/Homebrew → bộ phần mềm → dotfiles đã rà soát → key/credential qua kênh riêng → source → runtime pin version → dữ liệu database/ container → kiểm thử dự án. Không mang nguyên cache và cấu hình account cũ sang máy mới.

13. Checklist nghiệm thu máy mới

• macOS đã cập nhật; FileVault, khóa màn hình và firewall được cấu hình.
• Terminal native đúng kiến trúc; Homebrew prefix phù hợp và brew doctor đã được xem.
• Mở Terminal mới vẫn chạy được Git, Just, editor và runtime cần dùng.
• Font, bộ gõ, completion và plugin shell hoạt động; không có lỗi khi mở shell.
• SSH key có passphrase; chỉ public key được đăng ký; Git identity đúng repository.
• Mỗi dự án dùng phiên bản runtime/lockfile của chính nó và chạy được test cơ bản.
• Podman engine hoạt động và container hello chạy được; volume cần giữ đã có backup.
• Cloud profile/kube context đúng, chưa có credential hoặc endpoint nội bộ trong source.
• IDE mở dự án, tìm đúng interpreter/toolchain và chạy được formatter.
• Time Machine hoàn tất một backup và restore file mẫu thành công.

Các lệnh chẩn đoán nhanh, chỉ chạy phần đã cài:

brew doctor
brew services list
command -v git just uv
git --version
just --version
uv --version
podman info

14. Bảo trì và xử lý lỗi

Định kỳ xem cập nhật macOS, brew outdated, trạng thái service và dung lượng. Nâng cấp theo nhóm phù hợp lịch làm việc, sau đó chạy lại test dự án; database và runtime major version cần được xử lý riêng.

brew update
brew outdated
brew doctor
brew services list
df -h