Update README with M-chip mac instruction focus

[Janell-Huyck]

Update README: Add Apple Silicon M-Chip Setup Instructions

Summary

Complete rewrite of setup and installation documentation to provide clear, concise instructions optimized for Apple Silicon (M1–M4) Macs, with fallback instructions for Intel Macs. This resolves dependency installation failures that developers consistently encounter on new M-chip machines.

Rationale

The current README was written before Apple Silicon existed and contains:

• Generic instructions that assume x86 architecture
• Scattered, nested notes about M-chip workarounds
• No guidance on the critical OpenSSL 1.1.1 build requirement for Ruby 2.7.8
• Unclear Fedora setup (missing Java 8 configuration)
• No bundler version specification (causes incompatible gem installations)

The Problem:

• Ruby 2.7.8 requires OpenSSL < 3.0, but Homebrew dropped [email protected]
• Xcode 15+ enforces strict function pointer type checking (breaks nio4r, posix-spawn, mysql2 compilation)
• mysql2 0.5.x requires explicit linker paths for zstd and OpenSSL on M-chips
• Fedora requires Java 8, but modern Macs default to Java 21
• Modern bundler requires Ruby 3.2+ (need 2.4.22 for this app)

Without guidance, developers spend 2–4 hours troubleshooting native extension builds.

Changes

Organization

• System Requirements: Clear bulleted lists of dependencies, separated by M-chip vs Intel
• Quick Start: Single clone/checkout section
• 1. Install Dependencies: Step-by-step copy-paste commands
  • M-chip: Includes OpenSSL 1.1.1 build from source (only needed once)
  • Intel: Simpler Homebrew-only setup
• Running the Application: Terminal-by-terminal setup (Fedora → Solr → Redis → Rails)
• Running Tests: Same structure but with test ports/database setup
• Security Checks: Copy-paste vulnerability scan commands

Key Improvements

• ✅ All commands are copy-paste ready (no placeholders or manual substitutions)
• ✅ Explicit versions for Ruby, Bundler, and bundler environment variables
• ✅ Java 8 configuration for both Fedora dev and test runs
• ✅ Clear port numbers for each service (8984, 8983, 6379, 8080, 8985)
• ✅ Bundler config and environment variables documented for troubleshooting
• ✅ Admin user creation with exact Rails console commands
• ✅ Intel instructions provided (simpler, requires no custom OpenSSL build)

Testing This PR

1. Clone on a fresh M-chip Mac (or Intel) with Xcode 15+ installed
2. Follow the steps in "Install Dependencies" → "Running the Application"
3. Verify rails server starts and http://localhost:3000 is reachable
4. Run tests section and verify bundle exec rake spec works

Notes for Reviewers

• The OpenSSL 1.1.1 build step is required only once per machine; it's a one-time setup
• The CFLAGS and LDFLAGS exports are only needed during bundle install (not at runtime)
• Fedora's Java 8 requirement is enforced; newer JDKs cause fcrepo_wrapper to fail silently
• This README now assumes Homebrew is installed (reasonable for modern Mac dev setup)

---

Closes: LIBSCH1-70

---

The following are a series of screenshots of the updated README as it displays on GitHub. There is intentional duplication of the last line in the screenshot on the first line of the following screenshot to aid in getting the images in correct order. That duplication is not present in the README.

[haitzlm]

Clear. Good change to not load the js files repeatedly.