🚀 CubeShell Quick Start Guide

The ClassNotFoundException Fix

The error ClassNotFoundException: com.cube.shell.CubeShell occurs because the Java classpath doesn't include all dependencies. Here are three guaranteed working solutions:

✅ Method 1: Use run-shell.sh (EASIEST - RECOMMENDED)

This script uses Maven to handle all classpath issues automatically.

Linux/macOS:

# Make executable (first time only)
chmod +x run-shell.sh

# Run
./run-shell.sh

# With custom host/port
./run-shell.sh --host 192.168.1.100 --port 8080

Windows:

run-shell.bat

REM With custom host/port
run-shell.bat --host 192.168.1.100 --port 8080

Why this works:

Uses Maven's exec plugin
Maven automatically resolves all dependencies
No manual classpath configuration needed

✅ Method 2: Use Maven Directly

# Start with default settings (localhost:8080)
mvn exec:java -Dexec.mainClass="com.cube.shell.CubeShell"

# Start with custom host and port
mvn exec:java \
    -Dexec.mainClass="com.cube.shell.CubeShell" \
    -Dexec.args="--host 192.168.1.100 --port 8080"

Why this works:

Maven manages the entire classpath
All Spring Boot and Jackson dependencies are included
Works on any platform with Maven installed

✅ Method 3: Build and Run with Full JAR

# Step 1: Build the project
mvn clean package

# Step 2: Run the shell (connects to localhost:8080)
java -jar target/cube-db-1.0.0.jar com.cube.shell.CubeShell

# Note: This method requires modifying the JAR configuration
# Method 1 or 2 are simpler and recommended

Complete Setup Example

1. First Time Setup

# Clone/extract the project
cd cube-db

# Ensure you have Java 21+ and Maven
java -version   # Should show 21 or higher
mvn --version   # Should show Maven 3.6+

# Build the project
mvn clean compile

2. Start the Database Server (Terminal 1)

# Build if not already done
mvn clean package -DskipTests

# Start the server
java -jar target/cube-db-1.0.0.jar

# Or use Maven
mvn spring-boot:run

Wait for:

Started CubeApplication in X.XXX seconds

3. Start CubeShell (Terminal 2)

# Use the run-shell script (easiest)
./run-shell.sh

# Or use Maven directly
mvn exec:java -Dexec.mainClass="com.cube.shell.CubeShell"

Example Session

$ ./run-shell.sh

╔══════════════════════════════════════════════════════════╗
║              CubeShell v2.0.0                            ║
║         Distributed Database Interactive Shell          ║
║              Phase 2: Cluster Edition                   ║
╚══════════════════════════════════════════════════════════╝

✓ Java version: 21
✓ Connecting to: localhost:8080

🚀 Starting CubeShell...

╔══════════════════════════════════════════════════════════╗
║              CubeShell v2.0.0                            ║
║         Distributed Database Interactive Shell          ║
║              Phase 2: Cluster Edition                   ║
╚══════════════════════════════════════════════════════════╝

✓ Connected to localhost:8080
Type 'HELP' for available commands, 'EXIT' to quit.

cube> CONNECT localhost 8080
✓ Connected to localhost:8080
  Node ID: node-localhost-8080
  Set as current node

cube> CONSISTENCY QUORUM
✓ Consistency level set to QUORUM

cube> PUT user:alice "Alice Johnson"
✓ PUT successful
  Key: user:alice
  Value: Alice Johnson
  CL: QUORUM

cube> GET user:alice
✓ Found
  Key: user:alice
  Value: Alice Johnson
  CL: QUORUM

cube> NODES
╔════════════════════════════════════════════════════════════╗
║                    Cluster Nodes                           ║
╠════════════════════════════════════════════════════════════╣
║ ➜ ✓ node-localhost-8080  localhost:8080     DC:dc1        ║
╠════════════════════════════════════════════════════════════╣
║ Total Nodes: 1    Alive: 1    Current: node-localhost-8080║
╚════════════════════════════════════════════════════════════╝

cube> EXIT
Goodbye!

Troubleshooting

Issue: "Java not found"

# Install Java 21
# macOS:
brew install openjdk@21

# Ubuntu:
sudo apt-get install openjdk-21-jdk

# Verify
java -version

Issue: "Maven not found"

# Install Maven
# macOS:
brew install maven

# Ubuntu:
sudo apt-get install maven

# Verify
mvn --version

Issue: "Compilation failure"

# Clean and rebuild
mvn clean compile

# Check for errors in output
# Most common: wrong Java version or missing dependencies

Issue: "Connection refused"

# Make sure the database server is running
# In another terminal:
mvn spring-boot:run

# Or:
java -jar target/cube-db-1.0.0.jar

Issue: "Port 8080 already in use"

# Option 1: Use different port
./run-shell.sh --port 9090

# Option 2: Kill process using port 8080
# macOS/Linux:
lsof -ti:8080 | xargs kill -9

# Windows:
netstat -ano | findstr :8080
taskkill /PID <PID> /F

Command Reference

Connecting to Multiple Nodes

cube> CONNECT node1.local 8080
cube> CONNECT node2.local 8080
cube> CONNECT node3.local 8080
cube> NODES

Setting Consistency Levels

cube> CONSISTENCY ONE     # Fastest
cube> CONSISTENCY QUORUM  # Balanced (recommended)
cube> CONSISTENCY ALL     # Strongest

Data Operations

cube> PUT key value
cube> GET key
cube> DELETE key
cube> SCAN prefix:

Viewing Status

cube> STATUS             # Current node status
cube> STATS              # Replication statistics
cube> HISTORY            # Command history

Multi-Node Example

# Terminal 1: Start node 1
java -Dserver.port=8080 -Dcube.datadir=/tmp/node1 -jar target/cube-db-1.0.0.jar

# Terminal 2: Start node 2
java -Dserver.port=8081 -Dcube.datadir=/tmp/node2 -jar target/cube-db-1.0.0.jar

# Terminal 3: Start node 3
java -Dserver.port=8082 -Dcube.datadir=/tmp/node3 -jar target/cube-db-1.0.0.jar

# Terminal 4: Start shell and connect to all
./run-shell.sh

cube> CONNECT localhost 8080
cube> CONNECT localhost 8081
cube> CONNECT localhost 8082
cube> NODES
# Shows all 3 nodes

cube> CONSISTENCY QUORUM
cube> PUT test:key "replicated value"
# Writes to 2 of 3 nodes

Production Deployment

For production, you can create a systemd service or Docker container:

Systemd Service (Linux)

[Unit]
Description=Cube Database Shell
After=network.target

[Service]
Type=simple
User=cubedb
WorkingDirectory=/opt/cube-db
ExecStart=/opt/cube-db/run-shell.sh --host production-db --port 8080
Restart=on-failure

[Install]
WantedBy=multi-user.target

Docker

FROM openjdk:21-slim
RUN apt-get update && apt-get install -y maven
COPY . /app
WORKDIR /app
RUN mvn clean compile
CMD ["./run-shell.sh"]

Key Points to Remember

Always use run-shell.sh or Maven exec - These handle classpath automatically
Server must be running first - CubeShell connects to a running database
Default is localhost:8080 - Use --host and --port to change
Java 21+ required - Check with java -version
Maven must be installed - Check with mvn --version

Files Overview

File	Purpose	When to Use
`run-shell.sh`	Linux/macOS launcher	Primary method
`run-shell.bat`	Windows launcher	Windows users
`cubesh`	Alternative script	If Maven exec not preferred
`cubesh-simple`	Minimal Maven exec	Simple one-liner

Summary

✅ Easiest Method: ./run-shell.sh
✅ Most Reliable: Maven exec plugin
✅ Cross-Platform: Works on Linux, macOS, and Windows
✅ No Classpath Issues: Maven handles everything

You're ready to use CubeShell! 🎉

For more details, see:

CUBESHELL_GUIDE.md - Complete command reference
SHELL_STARTUP_FIX.md - Detailed troubleshooting
PHASE2_README.md - Replication features