CubeCactus - Build Instructions

Prerequisites Installation

Ubuntu/Debian

# Update package list
sudo apt update

# Install JDK 21
sudo apt install openjdk-21-jdk

# Install Maven
sudo apt install maven

# Verify installations
java -version    # Should show "21"
javac -version   # Should show "21"
mvn -version     # Should show "3.6" or higher

macOS

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Java 21
brew install openjdk@21

# Install Maven
brew install maven

# Link Java
sudo ln -sfn /usr/local/opt/openjdk@21/libexec/openjdk.jdk \
    /Library/Java/JavaVirtualMachines/openjdk-21.jdk

# Verify
java -version
mvn -version

Windows

# 1. Download and install JDK 21 from:
#    https://adoptium.net/

# 2. Download and install Maven from:
#    https://maven.apache.org/download.cgi

# 3. Add to PATH:
#    JAVA_HOME=C:\Program Files\Java\jdk-21
#    MAVEN_HOME=C:\Program Files\Apache\maven
#    PATH=%JAVA_HOME%\bin;%MAVEN_HOME%\bin

# 4. Verify in Command Prompt:
java -version
mvn -version

Build Steps

Step 1: Navigate to Source

cd cubecactus-source/

Step 2: Build with Maven

# Full build with tests
mvn clean package

# Skip tests (faster)
mvn clean package -DskipTests

# Verbose output
mvn clean package -X

Step 3: Verify Build

# Check if JAR was created
ls -lh target/cubecactus-1.0.0.jar

# Should show ~50MB file

Build Output

Successful build creates:

target/
├── cubecactus-1.0.0.jar           # Executable JAR (with dependencies)
├── cubecactus-1.0.0.jar.original  # Without dependencies
├── classes/                        # Compiled .class files
├── generated-sources/              # Generated code
├── maven-archiver/                 # Build metadata
└── maven-status/                   # Build status

Running the Application

Method 1: Run JAR Directly

java -jar target/cubecactus-1.0.0.jar

Method 2: Run with Maven

mvn spring-boot:run

Method 3: Run with Custom Port

java -Dserver.port=9090 -jar target/cubecactus-1.0.0.jar

Method 4: Run with Custom Configuration

java -jar target/cubecactus-1.0.0.jar \
  --server.port=8080 \
  --cube.node.id=node-1 \
  --cube.data.dir=/var/lib/cubecactus

Verify Installation

# Wait a few seconds for startup, then:

# Check health
curl http://localhost:8080/api/v1/health

# Should return:
# {"status":"UP"}

# Test SQL API
curl -X POST http://localhost:8080/api/v1/sql/execute \
  -H "Content-Type: application/json" \
  -d '{"sql": "CREATE TABLE test (id TEXT PRIMARY KEY, value TEXT)"}'

Build Profiles

Development Profile

mvn clean package -Pdev -DskipTests

Production Profile

mvn clean package -Pprod

Docker Profile

mvn clean package -Pdocker

Advanced Build Options

Parallel Build

# Use all CPU cores
mvn clean package -T 1C

# Use specific number of threads
mvn clean package -T 4

Offline Build

# Use cached dependencies
mvn clean package -o

Update Dependencies

# Force update from remote repositories
mvn clean package -U

Skip Specific Tests

mvn clean package -Dtest=!GossipProtocolTest

Troubleshooting Build Issues

Issue: "Failed to execute goal"

# Solution: Clean and rebuild
rm -rf target/
mvn clean install -U

Issue: "Cannot find symbol"

# Solution: Ensure Java 21
java -version  # Must show 21 or higher

# Verify Maven uses correct Java
mvn -version   # Check "Java version" line

Issue: "Connection timed out"

# Solution: Configure Maven proxy (if behind firewall)
# Edit ~/.m2/settings.xml:
<proxies>
  <proxy>
    <host>proxy.example.com</host>
    <port>8080</port>
  </proxy>
</proxies>

Issue: "Insufficient memory"

# Solution: Increase Maven memory
export MAVEN_OPTS="-Xmx2048m -XX:MaxPermSize=512m"
mvn clean package

Clean Build

# Remove all build artifacts
mvn clean

# Deep clean (including cached dependencies)
rm -rf target/ ~/.m2/repository/com/cube/
mvn clean install

IDE-Specific Build

IntelliJ IDEA

1. Import project (pom.xml)
2. Build → Build Project (Ctrl+F9)
3. Run → Run 'CubeApplication' (Shift+F10)

Eclipse

1. Import → Maven → Existing Maven Project
2. Project → Build Project
3. Run As → Java Application

VS Code

1. Open folder in VS Code
2. Maven sidebar → Execute → clean package
3. Run → Start Debugging (F5)

Continuous Integration

GitHub Actions

name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-java@v2
        with:
          java-version: '21'
      - run: mvn clean package

Jenkins

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        sh 'mvn clean package'
      }
    }
  }
}

Summary

✅ Install: JDK 21 + Maven 3.6+
✅ Build: mvn clean package
✅ Run: java -jar target/cubecactus-1.0.0.jar
✅ Test: curl http://localhost:8080/api/v1/health

Build time: ~2-5 minutes (first build downloads dependencies)
JAR size: ~50 MB
Memory: ~512 MB minimum

🌵 Happy Building!