📘 MSSU Developer Mac Setup

A clean, modern, reproducible Java + Grails + SQL development environment for macOS.

---

📑 Table of Contents

• ✨ Features
• 🚀 Quick Install
• 📁 Folder Structure
• 🧪 Validation Checklist
• 🧠 Manual Install (Optional)
• 🔧 Running Your First Project
• 🐛 Troubleshooting
• 🎉 You're Ready

---

✨ Features

• One-command environment setup (init.sh)
• Installs:
  • Homebrew + essential CLI tools
  • SDKMAN, Java 17, Grails 6
  • Oracle SQL Developer (GUI) + SQLcl (CLI)
  • iTerm2, Rectangle, AltTab
• Assumes a clean, opinionated development folder layout (documented below)
• Provides a tuned zsh setup with aliases & quality-of-life improvements

---

🚀 Quick Install

cd ~/Documents/Code/mssu
git clone https://github.com/Davis86t/mssu-dev-mac-setup
cd mssu-dev-mac-setup

chmod +x init.sh
./init.sh
source ~/.zshrc

---

⚠️ Known macOS Quirks (Read This Once)

This setup has been tested on Apple Silicon (M-series) Macs. A few platform realities are worth knowing up front.

Apple Silicon + Grails

• Grails 6 ships with an x86_64 (Intel) launcher.
• On Apple Silicon, Rosetta 2 is required to run Grails.
• If prompted by macOS, install Rosetta:

  softwareupdate --install-rosetta --agree-to-license

SDKMAN + nounset

• SDKMAN does not work correctly if nounset (set -u) is enabled.
• If you use strict shell modes, ensure nounset is disabled before SDKMAN initialization.
• This repository does not enforce shell strictness.

SQLcl (Not Provided by SDKMAN)

• SQLcl is not available via SDKMAN on macOS.
• SQLcl must be installed separately, typically via Homebrew:

  brew install --cask sqlcl

• The Homebrew cask installs SQLcl but does not add sql to PATH automatically.
• You may need to manually add SQLcl to your PATH:

  export PATH="/opt/homebrew/Caskroom/sqlcl/<version>/sqlcl/bin:$PATH"

These behaviors are properties of macOS and the upstream tools — not bugs in this repository.

---

📁 Folder Structure

This repository does not create directories automatically. The layout below documents the recommended local structure only.

Root: ~/Documents/
(avoids Desktop clutter, OneDrive sync issues, and IT permission problems)

~/Documents/
  Code/
    mssu/
      mssu-dev-mac-setup/   # THIS repo — Mac bootstrap & dev environment setup
      <other-repos>/        # MSSU application source code
    personal/               # Personal repos (optional)

  Dev/
    java/                   # JDKs, Java tooling notes, version references
    grails/                 # Grails SDK notes, framework-specific utilities
    databases/
      oracle/               # Oracle client tools, wallets, tnsnames (as permitted)
      postgres/             # Postgres scripts, dumps, local helpers (if needed)

  Projects/
    mssu/                   # Documentation ONLY (architecture notes, runbooks, diagrams)

  Sandbox/                  # Experiments, spikes, learning, throwaway code
  Bin/                      # User-level scripts added to PATH (no sudo)
  config/                   # Tool/app configs you maintain (replacement for ~/.config)

Rules

• Source code lives in Code/
• Setup & bootstrap repos live in Code/mssu/
• Docs never mix with code → Projects/
• SDKs & tooling ≠ repos → Dev/
• Nothing runs from OneDrive
• No sudo-owned files in your home directory

---

🧪 Validation Checklist

java -version
grails -version
brew --version
sql -version

---

🧠 Manual Install (Optional)

Install Oracle SQL Developer (GUI)

Oracle SQL Developer is used on campus for connecting to Oracle databases (ex: Banner).

1. Download SQL Developer for macOS from Oracle
2. Extract the zip
3. Launch the app and create a connection (host / port / service + credentials)

Official downloads:
https://www.oracle.com/database/sqldeveloper/technologies/download/

Note: SQLcl (installed by this repo) is the command-line companion to SQL Developer.

---

Install Xcode Tools

xcode-select --install

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Brewfile packages

brew bundle --file=Brewfile

Install SDKMAN + Java + Grails

curl -s "https://get.sdkman.io" | bash
source ~/.sdkman/bin/sdkman-init.sh

sdk install java 17.0.12-tem
sdk install grails 6.0.0

---

🔧 Running Your First Project

cd ~/Documents/Code/mssu
git clone <repo>
cd <project>
./gradlew bootRun

---

🐛 Troubleshooting

Issue	Solution
Grails not found	source ~/.zshrc
SQL Developer won't launch	Download the macOS build that includes the Oracle JDK
Permission denied	chmod +x gradlew

---

🎉 You're Ready

Your macOS machine is now fully equipped with:

• Java 17
• Grails 6
• Oracle SQL Developer / SQLcl
• Homebrew tooling
• A clean, professional folder layout

Start building. 🚀