Environment Setup

Automated environment setup and configuration for OpenGood computing environments

Pre-Requisites

• Access to GitHub with permissions to clone repos
• Familiarity with running commands and scripts from macOS Terminal

Compatibility

Installation is maintained for the recent version(s) of macOS and required processors:

Requirement	Version
macOS	Golden Gate 27.x
Processor	Apple Mx

---

Getting Started

• Open Terminal and type git
• One will be prompted to install the required Command Line Developer Tools
• Once installed, run the following commands from Terminal:

Create workspace Directory

mkdir -p ~/workspace

Download Repo

cd ~/workspace
git clone https://github.com/opengood-ai/env-setup
cd env-setup

---

Workstation Setup

Supported Packages

Base Packages (Core Tools)

• homebrew - Package manager for macOS
• vim - Text editor
• bash - Bash shell (5.0+)
• bash_it - Bash framework with themes and plugins
• git - Version control system

Required Packages (Standard Tools)

• appgrid - Application manager
• bats - Bash Automated Testing System
• claude_code - Anthropic's official CLI for Claude
• claude_desktop - Anthropic's official Claude Desktop app
• dockutil - Dock management utility
• gcc - GNU Compiler Collection
• google_chrome - Google Chrome web browser
• iterm - Terminal emulator for macOS
• jq - JSON processor
• maccy - Clipboard manager
• node - Node.js runtime
• obsidian - Knowledge base and note-taking app
• os_prefs - macOS preferences configuration
• pip - Python package installer
• pycharm - JetBrains IDE for Python
• python - Python programming language
• rectangle - Window management tool
• uv - Fast Python package installer and manager

Additional Packages (Optional Tools)

• chatgpt_desktop - OpenAI's official ChatGPT Desktop app
• docker_desktop - Docker Desktop container platform
• gnused - GNU implementation of sed
• gradle - Build automation tool
• intellij_idea - JetBrains IDE for Java/Kotlin
• java - Java Development Kit
• jenv - Java environment manager
• kafka - Distributed streaming platform
• kotlin - Kotlin programming language
• ktlint - Kotlin linter
• llama_cpp - C/C++ implementation for running LLMs locally
• neo4j_desktop - Graph database management system
• ollama - Run large language models locally
• postgres - PostgresSQL database
• sqlite - SQLite embedded database

---

Install Default Tools

bin/setup-workstation.sh install all

Notes:

• One will be prompted to enter credentials to grant elevated privileges to install packages
• One will be prompted to interactively enter the path to the Bash 5.0 or later shell, as this cannot be automated due to security restrictions in macOS requiring root level access to modify /etc/shells shells configuration file
• For Git, one will be prompted for the following information to complete the setup of various Git configurations:
  • Git name
  • Git email
  • GitHub username
  • GitHub access token
  • GitHub GPG signing key gpg signing key
• After Maacy and Rectangle are installed, one will need to open the System Preferences and grant them elevated privileges under Security & Privacy > Privacy > Accessibility

Install Specific Tools

bin/setup-workstation.sh install <package>

Customizing the Dock

The os_prefs package configures a core Dock layout shared by every workstation (packages/os_prefs.sh). To add personal apps on top of the core layout without committing them to this repo:

cp .custom-os-prefs.sh custom-os-prefs.sh

Edit .custom-os-prefs.sh and add dockutil --add entries for your own apps inside the install_custom_os_prefs() function. This file is gitignored, so it stays local. If .custom-os-prefs.sh is not present, os_prefs installs the core Dock layout only.

Uninstall Specific Tools

bin/setup-workstation.sh uninstall <package>

Uninstall All Tools

bin/setup-workstation.sh uninstall all

---

Custom Tools

Install/Update BMad

To install or update BMad-Method framework:

npx bmad-method install

---

Development

Run Tests

This project uses BATS (Bash Automated Testing System) for testing.

To run tests:

Pre-Requisites

Ensure bats is installed:

bin/setup-workstation.sh install bats

Run All Tests

# run commons utility function tests
bats test/commons.bats

# run package management tests
bats test/package.bats

Test Structure

• test/commons.bats - Tests for utility functions in modules/commons.sh
• test/package.bats - Tests for package management functions
• test/test-helper.bash - Test setup and utilities

Tests use bats-support and bats-assert libraries for enhanced assertions and output formatting.