diff --git a/Setup-for-a-MAC.md b/Setup-for-a-MAC.md new file mode 100644 index 0000000..495784e --- /dev/null +++ b/Setup-for-a-MAC.md @@ -0,0 +1,174 @@ + + +

Running Ballistic Builder (Spring Boot + Next.js) on macOS (zsh)

+

This guide explains how to run the Ballistic Builder Spring backend and the Next.js frontend locally on macOS using zsh.

+
+

Overview

+
+Component | Technology | Port +-- | -- | -- +Backend | Spring Boot (Java 21, Maven) | 8080 +Frontend | Next.js | 3000 +API Base Path | REST API | /api/v1 + +
+
+

Prerequisites

+ +
+

1. Install Required Tools

+

Install Homebrew (if not already installed)

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

Install dependencies

+
brew update
+brew install git maven node
+brew install --cask temurin@21
+
+

Verify installations

+
java -version     # Must be Java 21
+mvn -version
+node -v
+npm -v
+git --version
+
+
+

2. Configure Java 21 for zsh

+

Ensure Java 21 is the active JDK.

+

Add the following to your ~/.zshrc:

+
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
+export PATH="$JAVA_HOME/bin:$PATH"
+
+

Apply changes:

+
source ~/.zshrc
+
+

Confirm:

+
java -version
+mvn -version
+
+
+

3. Clone Repositories

+

Create a workspace directory:

+
mkdir -p ~/dev
+cd ~/dev
+
+

Clone the backend and frontend repositories:

+
git clone https://gitea.gofwd.group/Forward_Group/ballistic-builder-spring.git
+git clone https://gitea.gofwd.group/sean/shadow-gunbuilder-ai-proto.git
+
+
+

4. Run the Spring Boot Backend (Port 8080)

+

Open Terminal Window 1:

+
cd ~/dev/ballistic-builder-spring/ballistic-builder-spring
+mvn clean spring-boot:run
+
+

Backend will start at:

+
http://localhost:8080
+
+

API endpoints are available under:

+
http://localhost:8080/api/v1
+
+

Optional: Run as packaged JAR

+
mvn clean package
+java -jar target/*.jar
+
+
+

5. Configure Next.js API Proxy (Recommended)

+

To avoid CORS issues, Next.js should proxy API calls to Spring.

+

Edit or create:

+
shadow-gunbuilder-ai-proto/next.config.js
+
+
/** @type {import('next').NextConfig} */
+const nextConfig = {
+  async rewrites() {
+    return [
+      {
+        source: "/api/v1/:path*",
+        destination: "http://localhost:8080/api/v1/:path*",
+      },
+    ];
+  },
+};
+
+module.exports = nextConfig;
+
+
+

⚠️ Important: API version must be lowercase (/api/v1)

+
+
+

6. Run the Next.js Frontend (Port 3000)

+

Open Terminal Window 2:

+
cd ~/dev/shadow-gunbuilder-ai-proto
+npm install
+npm run dev
+
+

Frontend will be available at:

+
http://localhost:3000
+
+
+

7. Verify Connectivity

+

Backend test

+
curl http://localhost:8080/api/v1
+
+

Frontend proxy test

+
curl http://localhost:3000/api/v1
+
+

(Replace /api/v1 with a real endpoint if necessary.)

+
+

8. Common Issues & Fixes

+

Port already in use

+
lsof -i :8080
+lsof -i :3000
+
+

Stop a process:

+
kill -9 <PID>
+
+
+

Maven using wrong Java version

+
mvn -version
+
+

Fix:

+
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
+source ~/.zshrc
+
+
+

API returns 404

+ +
+

9. Running Both Services Together (Optional)

+

Using two terminals is recommended, but you can also run both with concurrently:

+
brew install concurrently
+
+
concurrently \
+  "cd ~/dev/ballistic-builder-spring/ballistic-builder-spring && mvn spring-boot:run" \
+  "cd ~/dev/shadow-gunbuilder-ai-proto && npm run dev"
+
+
+

Summary

+

✔ Java 21
+✔ Spring Boot on 8080
+✔ Next.js on 3000
+✔ API via /api/v1
+✔ macOS + zsh compatible

+ + \ No newline at end of file