sean/shadow-gunbuilder-ai-proto

Fork 0

Table of Contents

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

Overview
Prerequisites
1. Install Required Tools

Install Homebrew (if not already installed)
Install dependencies
Verify installations

2. Configure Java 21 for zsh
3. Clone Repositories
4. Run the Spring Boot Backend (Port 8080)

Optional: Run as packaged JAR

5. Configure Next.js API Proxy (Recommended)
6. Run the Next.js Frontend (Port 3000)
7. Verify Connectivity

Backend test
Frontend proxy test

8. Common Issues & Fixes

Port already in use
Maven using wrong Java version
API returns 404

9. Running Both Services Together (Optional)
Summary

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

Prerequisites

macOS
zsh (default shell on modern macOS)
Internet access to clone repositories

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

Confirm all paths use /api/v1 (lowercase)
Restart Next.js after changing next.config.js
Verify Spring controllers are mapped correctly

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

</html>