<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Documentation - CubeCactus</title>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600;800&family=Archivo:wght@300;500;900&display=swap" rel="stylesheet">
<link rel="stylesheet" href="index.html">
<style>
:root {
--primary: #00ff88;
--secondary: #0099ff;
--dark: #0a0e15;
--darker: #050810;
--light: #f0f4f8;
--accent: #ff0066;
--gray: #6b7280;
--border: rgba(0, 255, 136, 0.2);
--font-display: 'Archivo', sans-serif;
--font-mono: 'JetBrains Mono', monospace;
}
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: var(--font-mono);
background: var(--darker);
color: var(--light);
line-height: 1.6;
}
.docs-container {
max-width: 1400px;
margin: 0 auto;
padding: 6rem 2rem 2rem;
display: grid;
grid-template-columns: 300px 1fr;
gap: 4rem;
}
.sidebar {
position: sticky;
top: 100px;
height: fit-content;
}
.sidebar-section {
margin-bottom: 2rem;
}
.sidebar-title {
font-family: var(--font-display);
font-weight: 900;
color: var(--primary);
font-size: 0.85rem;
text-transform: uppercase;
letter-spacing: 0.1em;
margin-bottom: 1rem;
}
.sidebar-links {
list-style: none;
display: flex;
flex-direction: column;
gap: 0.5rem;
}
.sidebar-links a {
color: var(--gray);
text-decoration: none;
font-size: 0.9rem;
padding: 0.5rem 1rem;
border-left: 2px solid transparent;
transition: all 0.3s ease;
}
.sidebar-links a:hover,
.sidebar-links a.active {
color: var(--primary);
border-left-color: var(--primary);
background: rgba(0, 255, 136, 0.05);
}
.content {
max-width: 900px;
}
.doc-header {
margin-bottom: 3rem;
padding-bottom: 2rem;
border-bottom: 1px solid var(--border);
}
.doc-title {
font-family: var(--font-display);
font-size: 3.5rem;
font-weight: 900;
color: var(--light);
margin-bottom: 1rem;
}
.doc-subtitle {
font-size: 1.2rem;
color: var(--gray);
}
.content h2 {
font-family: var(--font-display);
font-size: 2rem;
font-weight: 900;
color: var(--light);
margin: 3rem 0 1.5rem;
padding-top: 2rem;
border-top: 1px solid var(--border);
}
.content h3 {
font-family: var(--font-display);
font-size: 1.5rem;
font-weight: 900;
color: var(--light);
margin: 2rem 0 1rem;
}
.content p {
color: var(--gray);
margin-bottom: 1.5rem;
line-height: 1.8;
}
.content code {
background: rgba(0, 255, 136, 0.1);
padding: 0.2rem 0.5rem;
border-radius: 4px;
font-family: var(--font-mono);
color: var(--primary);
font-size: 0.9em;
}
.code-block {
background: var(--dark);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1.5rem;
margin: 1.5rem 0;
overflow-x: auto;
}
.code-block pre {
color: var(--primary);
font-size: 0.9rem;
line-height: 1.8;
}
.info-box {
background: rgba(0, 153, 255, 0.1);
border-left: 4px solid var(--secondary);
padding: 1.5rem;
margin: 2rem 0;
border-radius: 4px;
}
.warning-box {
background: rgba(255, 153, 0, 0.1);
border-left: 4px solid #ff9900;
padding: 1.5rem;
margin: 2rem 0;
border-radius: 4px;
}
.feature-list {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 1.5rem;
margin: 2rem 0;
}
.feature-item {
background: rgba(0, 255, 136, 0.05);
border: 1px solid var(--border);
padding: 1.5rem;
border-radius: 8px;
}
.feature-item h4 {
color: var(--primary);
margin-bottom: 0.5rem;
font-family: var(--font-display);
font-weight: 900;
}
ul, ol {
margin: 1rem 0 1rem 2rem;
color: var(--gray);
}
li {
margin-bottom: 0.5rem;
}
table {
width: 100%;
border-collapse: collapse;
margin: 2rem 0;
}
th, td {
padding: 1rem;
text-align: left;
border-bottom: 1px solid var(--border);
}
th {
background: rgba(0, 255, 136, 0.05);
color: var(--primary);
font-family: var(--font-display);
font-weight: 900;
text-transform: uppercase;
font-size: 0.85rem;
}
td {
color: var(--gray);
}
</style>
</head>
<body>
<div class="docs-container">
<aside class="sidebar">
<div class="sidebar-section">
<h3 class="sidebar-title">Getting Started</h3>
<ul class="sidebar-links">
<li><a href="#quick-start" class="active">Quick Start</a></li>
<li><a href="#installation">Installation</a></li>
<li><a href="#first-cluster">First Cluster</a></li>
<li><a href="#basic-operations">Basic Operations</a></li>
</ul>
</div>
<div class="sidebar-section">
<h3 class="sidebar-title">Core Concepts</h3>
<ul class="sidebar-links">
<li><a href="#architecture">Architecture</a></li>
<li><a href="#data-model">Data Model</a></li>
<li><a href="#consistency">Consistency Levels</a></li>
<li><a href="#replication">Replication</a></li>
</ul>
</div>
<div class="sidebar-section">
<h3 class="sidebar-title">Features</h3>
<ul class="sidebar-links">
<li><a href="#sql">SQL Support</a></li>
<li><a href="#gossip">Gossip Protocol</a></li>
<li><a href="#storage">LSM Storage</a></li>
<li><a href="#api">REST API</a></li>
</ul>
</div>
<div class="sidebar-section">
<h3 class="sidebar-title">Deployment</h3>
<ul class="sidebar-links">
<li><a href="#docker">Docker</a></li>
<li><a href="#kubernetes">Kubernetes</a></li>
<li><a href="#production">Production</a></li>
</ul>
</div>
</aside>
<main class="content">
<div class="doc-header">
<h1 class="doc-title">Documentation</h1>
<p class="doc-subtitle">Everything you need to build with CubeDB</p>
</div>
<section id="quick-start">
<h2>Quick Start</h2>
<p>Get CubeDB up and running in under 5 minutes.</p>
<h3>Prerequisites</h3>
<ul>
<li>Java 21 or later</li>
<li>Maven 3.6+</li>
<li>4GB RAM minimum</li>
</ul>
<h3>Build from Source</h3>
<div class="code-block">
<pre># Clone repository
git clone https://github.com/cubecactus/cubecactus.git
cd cubecactus
# Build
mvn clean package -DskipTests
# Run single node
java -jar target/cubecactus-1.0.0.jar \
--node-id=node-1 \
--port=8080</pre>
</div>
<div class="info-box">
<strong>✓ Success!</strong> CubeCactus is now running on http://localhost:8080
</div>
<h3>Execute Your First Query</h3>
<div class="code-block">
<pre># Create a table
curl -X POST http://localhost:8080/api/v1/sql/execute \
-H "Content-Type: application/json" \
-d '{"sql": "CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT, email TEXT)"}'
# Insert data
curl -X POST http://localhost:8080/api/v1/sql/execute \
-H "Content-Type: application/json" \
-d '{"sql": "INSERT INTO users VALUES ('\''1'\'', '\''Alice'\'', '\''alice@example.com'\'')"}'
# Query data
curl -X POST http://localhost:8080/api/v1/sql/execute \
-H "Content-Type: application/json" \
-d '{"sql": "SELECT * FROM users WHERE id = '\''1'\''"}'</pre>
</div>
</section>
<section id="installation">
<h2>Installation</h2>
<h3>Docker</h3>
<div class="code-block">
<pre># Pull image
docker pull cubecactus/cubecactus:latest
# Run
docker run -d \
--name cubecactus \
-p 8080:8080 \
cubecactus/cubecactus:latest</pre>
</div>
<h3>Docker Compose (3-Node Cluster)</h3>
<div class="code-block">
<pre># Start cluster
docker-compose up -d
# Check status
docker-compose ps</pre>
</div>
<h3>Kubernetes</h3>
<div class="code-block">
<pre># Deploy StatefulSet
kubectl apply -f k8s/statefulset.yaml
# Check pods
kubectl get pods -n cubedb</pre>
</div>
</section>
<section id="architecture">
<h2>Architecture</h2>
<p>CubeCactus is a distributed column-family database inspired by Apache Cassandra, built with modern cloud-native principles.</p>
<h3>Core Components</h3>
<div class="feature-list">
<div class="feature-item">
<h4>LSM Storage Engine</h4>
<p>Write-optimized storage with MemTable, SSTable, and WAL</p>
</div>
<div class="feature-item">
<h4>Gossip Protocol</h4>
<p>SWIM-based membership and failure detection</p>
</div>
<div class="feature-item">
<h4>Query Engine</h4>
<p>SQL and CQL parser with query execution</p>
</div>
<div class="feature-item">
<h4>Replication Manager</h4>
<p>Configurable RF with hinted handoff</p>
</div>
</div>
</section>
<section id="consistency">
<h2>Consistency Levels</h2>
<p>CubeDB supports tunable consistency for read and write operations.</p>
<table>
<thead>
<tr>
<th>Level</th>
<th>Description</th>
<th>Use Case</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>ONE</code></td>
<td>Fastest, returns after 1 node responds</td>
<td>High throughput, eventual consistency</td>
</tr>
<tr>
<td><code>QUORUM</code></td>
<td>Majority of replicas (RF/2 + 1)</td>
<td>Balanced performance and consistency</td>
</tr>
<tr>
<td><code>ALL</code></td>
<td>All replicas must respond</td>
<td>Strong consistency, critical data</td>
</tr>
</tbody>
</table>
</section>
<section id="sql">
<h2>SQL Support</h2>
<p>CubeDB supports standard SQL syntax for familiar database operations.</p>
<h3>Supported Operations</h3>
<div class="code-block">
<pre>-- CREATE TABLE
CREATE TABLE users (
id TEXT PRIMARY KEY,
name TEXT,
email TEXT,
age TEXT
);
-- INSERT
INSERT INTO users (id, name, email, age)
VALUES ('1', 'Alice', 'alice@example.com', '30');
-- SELECT
SELECT * FROM users WHERE id = '1';
SELECT name, email FROM users WHERE id = '1';
-- UPDATE
UPDATE users SET age = '31' WHERE id = '1';
-- DELETE
DELETE FROM users WHERE id = '1';</pre>
</div>
</section>
<section id="gossip">
<h2>Gossip Protocol</h2>
<p>CubeCactus uses SWIM (Scalable Weakly-consistent Infection-style Membership) protocol for cluster membership.</p>
<h3>How It Works</h3>
<ol>
<li><strong>Heartbeat</strong>: Nodes increment heartbeat counters every gossip interval</li>
<li><strong>State Exchange</strong>: Nodes randomly select 3 peers and exchange cluster state</li>
<li><strong>Failure Detection</strong>: Nodes missing heartbeats are marked SUSPECTED, then DEAD</li>
<li><strong>Convergence</strong>: All nodes eventually see consistent cluster state</li>
</ol>
<div class="warning-box">
<strong>⚠ Configuration</strong>: Tune gossip intervals and timeouts based on your network latency. Default values work for most deployments.
</div>
</section>
<section id="docker">
<h2>Docker Deployment</h2>
<h3>Single Node</h3>
<div class="code-block">
<pre>docker run -d \
--name cubecactus-node1 \
-p 8080:8080 \
-e NODE_ID=node-1 \
-v cubecactus-data:/var/lib/cube/data \
cubecactus/cubecactus:latest</pre>
</div>
<h3>3-Node Cluster</h3>
<div class="code-block">
<pre># Use docker-compose.yml
services:
cubecactus-node-1:
image: cubecactus/cubecactus:latest
ports:
- "8080:8080"
environment:
- NODE_ID=node-1
- SEEDS=cubecactus-node-2:7946,cubecactus-node-3:7946
cubecactus-node-2:
image: cubecactus/cubecactus:latest
ports:
- "8081:8080"
environment:
- NODE_ID=node-2
- SEEDS=cubecactus-node-1:7946,cubecactus-node-3:7946
cubecactus-node-3:
image: cubecactus/cubecactus:latest
ports:
- "8082:8080"
environment:
- NODE_ID=node-3
- SEEDS=cubecactus-node-1:7946,cubecactus-node-2:7946</pre>
</div>
</section>
<section id="production">
<h2>Production Deployment</h2>
<h3>Best Practices</h3>
<ul>
<li><strong>Replication Factor</strong>: Use RF=3 for production</li>
<li><strong>Consistency</strong>: Use QUORUM for balanced performance</li>
<li><strong>Monitoring</strong>: Enable metrics and health checks</li>
<li><strong>Backups</strong>: Regular snapshots of data directories</li>
<li><strong>Resources</strong>: Minimum 4 cores, 8GB RAM per node</li>
</ul>
<h3>Scaling</h3>
<div class="code-block">
<pre># Add new node to cluster
java -jar cubecactus.jar \
--node-id=node-4 \
--port=8083 \
--seeds=node1:7946,node2:7946,node3:7946
# Verify cluster
curl http://localhost:8080/api/v1/cluster/status</pre>
</div>
</section>
</main>
</div>
<script>
// Smooth scrolling for anchor links
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
anchor.addEventListener('click', function (e) {
e.preventDefault();
const target = document.querySelector(this.getAttribute('href'));
if (target) {
target.scrollIntoView({ behavior: 'smooth', block: 'start' });
// Update active link
document.querySelectorAll('.sidebar-links a').forEach(link => {
link.classList.remove('active');
});
this.classList.add('active');
}
});
});
// Highlight current section in sidebar
const sections = document.querySelectorAll('section[id]');
const sidebarLinks = document.querySelectorAll('.sidebar-links a');
window.addEventListener('scroll', () => {
let current = '';
sections.forEach(section => {
const sectionTop = section.offsetTop;
if (pageYOffset >= sectionTop - 200) {
current = section.getAttribute('id');
}
});
sidebarLinks.forEach(link => {
link.classList.remove('active');
if (link.getAttribute('href') === `#${current}`) {
link.classList.add('active');
}
});
});
</script>
</body>
</html>
