Unix Administration (macOS + Linux)

Requires: macOS or native Linux (NOT WSL)

---

Navigation

• Troubleshooting & known issues: references/OPERATIONS.md
• Environment verification: scripts/verify-unix-environment.sh

---

Platform Detection

OS=$(uname -s)
case "$OS" in
    Darwin)
        echo "macOS"
        ;;
    Linux)
        if grep -qi microsoft /proc/version 2>/dev/null; then
            echo "WSL detected - use admin-wsl instead"
            exit 1
        fi
        echo "Native Linux"
        ;;
esac

---

Quick Start

# Verify environment first
bash scripts/verify-unix-environment.sh

# Load profile
source /path/to/admin/scripts/load-profile.sh
load_admin_profile
show_admin_summary

---

Package Management (Profile-Aware)

Check Preference First

PKG_MGR=$(jq -r '.preferences.packages.manager' "$PROFILE_PATH")

macOS (Homebrew)

brew install $package      # Install
brew upgrade $package      # Update
brew list                  # List installed
brew search $package       # Search

Linux (apt - Debian/Ubuntu)

sudo apt update
sudo apt install -y $package
sudo apt upgrade -y

Linux (dnf - Fedora/RHEL)

sudo dnf install -y $package
sudo dnf update -y

---

Python Commands (Profile-Aware)

PY_MGR=$(get_preferred_manager python)

case "$PY_MGR" in
    uv)     uv pip install "$package" ;;
    pip)    pip3 install "$package" ;;
    conda)  conda install "$package" ;;
esac

---

Node Commands (Profile-Aware)

NODE_MGR=$(get_preferred_manager node)

case "$NODE_MGR" in
    npm)    npm install "$package" ;;
    pnpm)   pnpm add "$package" ;;
    yarn)   yarn add "$package" ;;
    bun)    bun add "$package" ;;
esac

---

Services

Linux (systemd)

sudo systemctl status $service
sudo systemctl start $service
sudo systemctl stop $service
sudo systemctl restart $service
sudo systemctl enable $service    # Start on boot
sudo systemctl disable $service

journalctl -u $service -f         # View logs

macOS (Homebrew services)

brew services list
brew services start $service
brew services stop $service
brew services restart $service

---

SSH to Servers

Use the loader helper:

ssh_to_server "cool-two"

Or manually:

SERVER=$(jq '.servers[] | select(.id == "cool-two")' "$PROFILE_PATH")
HOST=$(echo "$SERVER" | jq -r '.host')
USER=$(echo "$SERVER" | jq -r '.username')
KEY=$(echo "$SERVER" | jq -r '.keyPath')

ssh -i "$KEY" "$USER@$HOST"

---

Docker Operations

# Verify Docker working
docker info

# Common commands
docker ps
docker logs <container>
docker exec -it <c> bash
docker-compose up -d

macOS: Start Docker Desktop app if daemon not running. Linux: sudo systemctl start docker

---

Capabilities Check

has_capability "hasDocker" && docker info
has_capability "hasGit" && git --version

---

Scope Boundaries

Task	Handle Here	Route To
Homebrew (macOS)	✅	-
apt/dnf/pacman (Linux)	✅	-
systemd services	✅	-
brew services (macOS)	✅	-
Python/Node	✅	-
Docker	✅	-
SSH to servers	✅	-
WSL operations	❌	admin-wsl
Windows operations	❌	admin-windows
Server provisioning	❌	admin-devops

---

References

• references/OPERATIONS.md - Known issues, platform-specific notes, troubleshooting, setup checklist