kogral/docs/book/guides/installation.html
2026-01-23 16:11:07 +00:00

511 lines
22 KiB
HTML

<!DOCTYPE HTML>
<html lang="en" class="rust sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Installation - KOGRAL Documentation</title>
<!-- Custom HTML head -->
<meta name="description" content="Complete documentation for KOGRAL - Git-native knowledge graphs for developer teams">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="../favicon.svg">
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "rust";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd></kbd> or <kbd></kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('rust')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">KOGRAL Documentation</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/your-org/knowledge-base" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<a href="https://github.com/your-org/knowledge-base/edit/main/docs/./guides/installation.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="installation"><a class="header" href="#installation">Installation</a></h1>
<p>This guide covers installing and setting up the KOGRAL.</p>
<h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2>
<h3 id="required"><a class="header" href="#required">Required</a></h3>
<ul>
<li>
<p><strong>Rust</strong> 1.70 or later</p>
<pre><code class="language-bash">curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
</code></pre>
</li>
<li>
<p><strong>Nickel</strong> CLI for configuration management</p>
<pre><code class="language-bash">cargo install nickel-lang-cli
</code></pre>
</li>
</ul>
<h3 id="optional"><a class="header" href="#optional">Optional</a></h3>
<ul>
<li>
<p><strong>NuShell</strong> for maintenance scripts</p>
<pre><code class="language-bash">cargo install nu
</code></pre>
</li>
<li>
<p><strong>SurrealDB</strong> for scalable storage backend</p>
<pre><code class="language-bash"># macOS
brew install surrealdb/tap/surreal
# Linux/Windows
curl -sSf https://install.surrealdb.com | sh
</code></pre>
</li>
</ul>
<h2 id="installation-methods"><a class="header" href="#installation-methods">Installation Methods</a></h2>
<h3 id="method-1-install-from-source-recommended"><a class="header" href="#method-1-install-from-source-recommended">Method 1: Install from Source (Recommended)</a></h3>
<pre><code class="language-bash"># Clone the repository
git clone &lt;repository-url&gt; knowledge-base
cd knowledge-base
# Build the workspace
cargo build --release
# Install CLI tool
cargo install --path crates/kb-cli
# Verify installation
kb --version
</code></pre>
<h3 id="method-2-build-specific-crates"><a class="header" href="#method-2-build-specific-crates">Method 2: Build Specific Crates</a></h3>
<pre><code class="language-bash"># Build only kb-core library
cargo build --package kb-core --release
# Build only kb-cli
cargo build --package kb-cli --release
# Build only kogral-mcp server
cargo build --package kb-mcp --release
</code></pre>
<h3 id="method-3-build-with-features"><a class="header" href="#method-3-build-with-features">Method 3: Build with Features</a></h3>
<pre><code class="language-bash"># Build with all features (filesystem + SurrealDB + fastembed)
cargo build --workspace --all-features --release
# Build with specific features
cargo build --package kb-core --features "surrealdb,fastembed" --release
</code></pre>
<h2 id="feature-flags"><a class="header" href="#feature-flags">Feature Flags</a></h2>
<p>kb-core supports optional features:</p>
<div class="table-wrapper"><table><thead><tr><th>Feature</th><th>Description</th><th>Default</th></tr></thead><tbody>
<tr><td><code>filesystem</code></td><td>Filesystem storage backend</td><td>✅ Yes</td></tr>
<tr><td><code>surrealdb</code></td><td>SurrealDB storage backend</td><td>❌ No</td></tr>
<tr><td><code>fastembed</code></td><td>Local embedding generation</td><td>❌ No</td></tr>
<tr><td><code>full</code></td><td>All features enabled</td><td>❌ No</td></tr>
</tbody></table>
</div>
<p>Example usage:</p>
<pre><code class="language-bash"># Enable SurrealDB backend
cargo build --features surrealdb
# Enable all features
cargo build --features full
</code></pre>
<h2 id="environment-setup"><a class="header" href="#environment-setup">Environment Setup</a></h2>
<h3 id="1-initialize-a-knowledge-base"><a class="header" href="#1-initialize-a-knowledge-base">1. Initialize a Knowledge Base</a></h3>
<pre><code class="language-bash"># Navigate to your project
cd /path/to/your/project
# Initialize .kb directory
kb init
# Or initialize with custom name
kb init --name "My Project" --description "Project knowledge base"
</code></pre>
<p>This creates:</p>
<pre><code>your-project/
└── .kogral/
├── config.toml
├── notes/
├── decisions/
├── guidelines/
├── patterns/
└── journal/
</code></pre>
<h3 id="2-configure-nickel-schemas-optional"><a class="header" href="#2-configure-nickel-schemas-optional">2. Configure Nickel Schemas (Optional)</a></h3>
<p>If you want advanced configuration:</p>
<pre><code class="language-bash"># Copy default config
cp /path/to/knowledge-base/config/defaults.ncl .kogral/config.ncl
# Edit configuration
$EDITOR .kogral/config.ncl
# Export to TOML (for kb-cli compatibility)
nickel export --format json .kogral/config.ncl | kb config import
</code></pre>
<h3 id="3-set-up-shared-knowledge-base-optional"><a class="header" href="#3-set-up-shared-knowledge-base-optional">3. Set Up Shared Knowledge Base (Optional)</a></h3>
<p>For shared guidelines and patterns across projects:</p>
<pre><code class="language-bash"># Create shared KB location
mkdir -p ~/Tools/.kogral-shared
cd ~/Tools/.kogral-shared
# Initialize shared KB
kb init --name "Shared Knowledge" --description "Cross-project guidelines"
# Configure inheritance in project
kb config set inheritance.base ~/Tools/.kogral-shared
</code></pre>
<h2 id="verify-installation"><a class="header" href="#verify-installation">Verify Installation</a></h2>
<h3 id="test-cli"><a class="header" href="#test-cli">Test CLI</a></h3>
<pre><code class="language-bash"># Check version
kb --version
# Show help
kb --help
# Test initialization (dry-run)
kb init --dry-run
</code></pre>
<h3 id="test-mcp-server"><a class="header" href="#test-mcp-server">Test MCP Server</a></h3>
<pre><code class="language-bash"># Start MCP server in test mode
kb serve --transport stdio
# In another terminal, test with echo
echo '{"jsonrpc":"2.0","id":1,"method":"kogral/search","params":{"query":"test"}}' | kb serve
</code></pre>
<h3 id="run-tests"><a class="header" href="#run-tests">Run Tests</a></h3>
<pre><code class="language-bash"># Run all tests
cargo test --workspace
# Run integration tests
cargo test --package kb-core --test '*'
# Run with all features
cargo test --workspace --all-features
</code></pre>
<h2 id="surrealdb-setup-optional"><a class="header" href="#surrealdb-setup-optional">SurrealDB Setup (Optional)</a></h2>
<p>If using SurrealDB backend:</p>
<h3 id="start-surrealdb-server"><a class="header" href="#start-surrealdb-server">Start SurrealDB Server</a></h3>
<pre><code class="language-bash"># Start server
surreal start --log trace --user root --pass root file://data.db
# Or use memory backend for testing
surreal start --log trace --user root --pass root memory
</code></pre>
<h3 id="configure-kb-core"><a class="header" href="#configure-kb-core">Configure kb-core</a></h3>
<p>Edit <code>.kogral/config.ncl</code>:</p>
<pre><code class="language-nickel">{
storage = {
primary = 'filesystem,
secondary = {
enabled = true,
type = 'surrealdb,
url = "ws://localhost:8000",
namespace = "kb",
database = "default",
username = "root",
password = "root",
},
},
}
</code></pre>
<h3 id="initialize-schema"><a class="header" href="#initialize-schema">Initialize Schema</a></h3>
<pre><code class="language-bash"># Run migration script
nu scripts/kb-migrate.nu --target latest
# Or manually import schema
surreal import --conn ws://localhost:8000 --user root --pass root --ns kb --db default schema.surql
</code></pre>
<h2 id="embedding-provider-setup-optional"><a class="header" href="#embedding-provider-setup-optional">Embedding Provider Setup (Optional)</a></h2>
<h3 id="local-fastembed"><a class="header" href="#local-fastembed">Local fastembed</a></h3>
<pre><code class="language-bash"># Build with fastembed feature
cargo build --package kb-core --features fastembed
# Models will be downloaded on first use
</code></pre>
<h3 id="api-providers-openai-claude-ollama"><a class="header" href="#api-providers-openai-claude-ollama">API Providers (OpenAI, Claude, Ollama)</a></h3>
<p>Set environment variables:</p>
<pre><code class="language-bash"># OpenAI
export OPENAI_API_KEY="sk-..."
# Claude (Anthropic)
export ANTHROPIC_API_KEY="sk-ant-..."
# Ollama (local)
export OLLAMA_API_BASE="http://localhost:11434"
</code></pre>
<p>Configure provider in <code>.kogral/config.ncl</code>:</p>
<pre><code class="language-nickel">{
embeddings = {
enabled = true,
provider = 'openai, # or 'claude, 'ollama, 'fastembed
model = "text-embedding-3-small",
api_key_env = "OPENAI_API_KEY",
},
}
</code></pre>
<h2 id="claude-code-integration"><a class="header" href="#claude-code-integration">Claude Code Integration</a></h2>
<p>To use kb-mcp with Claude Code:</p>
<h3 id="1-build-mcp-server"><a class="header" href="#1-build-mcp-server">1. Build MCP Server</a></h3>
<pre><code class="language-bash">cargo build --package kb-mcp --release
</code></pre>
<h3 id="2-configure-claude-code"><a class="header" href="#2-configure-claude-code">2. Configure Claude Code</a></h3>
<p>Add to <code>~/.config/claude/config.json</code>:</p>
<pre><code class="language-json">{
"mcpServers": {
"kogral-mcp": {
"command": "/path/to/knowledge-base/target/release/kb-mcp",
"args": ["serve"],
"env": {}
}
}
}
</code></pre>
<h3 id="3-test-connection"><a class="header" href="#3-test-connection">3. Test Connection</a></h3>
<p>Start Claude Code and verify:</p>
<pre><code>&gt; kb/search "test"
</code></pre>
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
<h3 id="nickel-not-found"><a class="header" href="#nickel-not-found">Nickel Not Found</a></h3>
<pre><code class="language-bash"># Verify nickel is installed
nickel --version
# If not, install
cargo install nickel-lang-cli
# Add cargo bin to PATH
export PATH="$HOME/.cargo/bin:$PATH"
</code></pre>
<h3 id="compilation-errors"><a class="header" href="#compilation-errors">Compilation Errors</a></h3>
<pre><code class="language-bash"># Update Rust
rustup update stable
# Clean and rebuild
cargo clean
cargo build --workspace
</code></pre>
<h3 id="surrealdb-connection-failed"><a class="header" href="#surrealdb-connection-failed">SurrealDB Connection Failed</a></h3>
<pre><code class="language-bash"># Check SurrealDB is running
curl http://localhost:8000/health
# Start SurrealDB with correct settings
surreal start --bind 0.0.0.0:8000 --user root --pass root memory
</code></pre>
<h3 id="mcp-server-not-responding"><a class="header" href="#mcp-server-not-responding">MCP Server Not Responding</a></h3>
<pre><code class="language-bash"># Test stdio communication
echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | kb serve
# Check logs
kb serve --log-level debug
</code></pre>
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
<ul>
<li><a href="user-guide/quickstart.html">Quick Start Guide</a> - Create your first knowledge base</li>
<li><a href="user-guide/configuration.html">Configuration Reference</a> - Customize behavior</li>
<li><a href="api/mcp-tools.html">MCP Tools</a> - Integrate with Claude Code</li>
</ul>
<h2 id="uninstallation"><a class="header" href="#uninstallation">Uninstallation</a></h2>
<pre><code class="language-bash"># Remove installed binary
cargo uninstall kb-cli
# Remove project knowledge base
rm -rf /path/to/project/.kogral
# Remove shared knowledge base
rm -rf ~/Tools/.kogral-shared
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../kogral/design-philosophy.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../guides/quickstart.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../kogral/design-philosophy.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../guides/quickstart.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>