# 🚀 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:
```bash
# 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:
```batch
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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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)

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

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

---

## Example Session

```bash
$ ./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"
```bash
# Install Java 21
# macOS:
brew install openjdk@21

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

# Verify
java -version
```

### Issue: "Maven not found"
```bash
# Install Maven
# macOS:
brew install maven

# Ubuntu:
sudo apt-get install maven

# Verify
mvn --version
```

### Issue: "Compilation failure"
```bash
# Clean and rebuild
mvn clean compile

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

### Issue: "Connection refused"
```bash
# 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"
```bash
# 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
```bash
cube> CONNECT node1.local 8080
cube> CONNECT node2.local 8080
cube> CONNECT node3.local 8080
cube> NODES
```

### Setting Consistency Levels
```bash
cube> CONSISTENCY ONE     # Fastest
cube> CONSISTENCY QUORUM  # Balanced (recommended)
cube> CONSISTENCY ALL     # Strongest
```

### Data Operations
```bash
cube> PUT key value
cube> GET key
cube> DELETE key
cube> SCAN prefix:
```

### Viewing Status
```bash
cube> STATUS             # Current node status
cube> STATS              # Replication statistics
cube> HISTORY            # Command history
```

---

## Multi-Node Example

```bash
# 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)
```ini
[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
```dockerfile
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

1. **Always use `run-shell.sh` or Maven exec** - These handle classpath automatically
2. **Server must be running first** - CubeShell connects to a running database
3. **Default is localhost:8080** - Use `--host` and `--port` to change
4. **Java 21+ required** - Check with `java -version`
5. **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