<!-- CANARY: REQ=REQ-DOCS-001; FEATURE="Docs"; ASPECT=Documentation; STATUS=TESTED; OWNER=docs; UPDATED=2026-01-15 -->
<h2 id="installation-and-quick-start" class="position-relative d-flex align-items-center group">
<span>Installation and Quick Start</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="installation-and-quick-start"
aria-haspopup="dialog"
aria-label="Share link: Installation and Quick Start">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h2><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden>
<div class="hsm-dialog" role="document">
<div class="hsm-header">
<h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2>
<button type="button" class="hsm-close" aria-label="Close">
<i class="fa-solid fa-xmark"></i>
</button>
</div>
<div class="hsm-body">
<label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label>
<div class="input-group mb-4 hsm-url-group">
<input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" />
<button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy">
<i class="fa-duotone fa-clipboard" aria-hidden="true"></i>
</button>
</div>
<div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div>
<div class="hsm-share-grid">
<a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-twitter me-2"></i>Twitter
</a>
<a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-linkedin me-2"></i>LinkedIn
</a>
<a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-facebook me-2"></i>Facebook
</a>
</div>
</div>
</div>
</div>
<style>
.heading-share-modal {
position: fixed;
inset: 0;
display: flex;
justify-content: center;
align-items: center;
background: rgba(0, 0, 0, 0.6);
z-index: 1050;
padding: 1rem;
backdrop-filter: blur(4px);
-webkit-backdrop-filter: blur(4px);
}
.heading-share-modal[hidden] { display: none !important; }
.hsm-dialog {
max-width: 420px;
width: 100%;
background: var(--bs-body-bg, #fff);
color: var(--bs-body-color, #212529);
border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1));
border-radius: 1rem;
box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
overflow: hidden;
animation: hsm-fade-in 0.2s ease-out;
}
@keyframes hsm-fade-in {
from { opacity: 0; transform: scale(0.95); }
to { opacity: 1; transform: scale(1); }
}
[data-bs-theme="dark"] .hsm-dialog {
background: #1e293b;
border-color: rgba(255,255,255,0.1);
color: #f8f9fa;
}
.hsm-header {
display: flex;
justify-content: space-between;
align-items: center;
padding: 1rem 1.5rem;
border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1));
background: rgba(0,0,0,0.02);
}
[data-bs-theme="dark"] .hsm-header {
background: rgba(255,255,255,0.02);
border-color: rgba(255,255,255,0.1);
}
.hsm-close {
background: transparent;
border: none;
color: inherit;
opacity: 0.5;
padding: 0.25rem 0.5rem;
border-radius: 0.25rem;
font-size: 1.2rem;
line-height: 1;
transition: opacity 0.2s;
}
.hsm-close:hover {
opacity: 1;
}
.hsm-body {
padding: 1.5rem;
}
.hsm-url-group {
display: flex !important;
align-items: stretch;
}
.hsm-url-group .form-control {
flex: 1;
min-width: 0;
margin: 0;
background: var(--bs-secondary-bg, #f8f9fa);
border-color: var(--bs-border-color, #dee2e6);
border-top-right-radius: 0;
border-bottom-right-radius: 0;
height: 42px;
}
.hsm-url-group .btn {
flex: 0 0 auto;
margin: 0;
margin-left: -1px;
border-top-left-radius: 0;
border-bottom-left-radius: 0;
height: 42px;
display: flex;
align-items: center;
justify-content: center;
padding: 0 1.25rem;
z-index: 2;
}
[data-bs-theme="dark"] .hsm-url-group .form-control {
background: #0f172a;
border-color: #334155;
color: #e2e8f0;
}
.hsm-share-grid {
display: flex;
flex-direction: column;
gap: 0.5rem;
}
.hsm-share-grid .btn {
display: flex;
align-items: center;
justify-content: center;
font-size: 0.9rem;
padding: 0.6rem;
border-color: var(--bs-border-color);
width: 100%;
}
[data-bs-theme="dark"] .hsm-share-grid .btn {
color: #e2e8f0;
border-color: #475569;
}
[data-bs-theme="dark"] .hsm-share-grid .btn:hover {
background: #334155;
border-color: #cbd5e1;
}
</style>
<script>
(function(){
const modal = document.getElementById('headingShareModal');
if(!modal) return;
const input = modal.querySelector('#headingShareInput');
const copyBtn = modal.querySelector('.hsm-copy');
const twitter = modal.querySelector('#share-twitter');
const linkedin = modal.querySelector('#share-linkedin');
const facebook = modal.querySelector('#share-facebook');
const closeBtn = modal.querySelector('.hsm-close');
let lastFocus=null;
let trapBound=false;
function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; }
function isOpen(){ return !modal.hasAttribute('hidden'); }
function hydrate(id){
const url=buildUrl(id);
input.value=url;
const enc=encodeURIComponent(url);
const text=encodeURIComponent(document.title);
if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`;
if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`;
if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`;
}
function openModal(id){
lastFocus=document.activeElement;
hydrate(id);
if(!isOpen()){
modal.removeAttribute('hidden');
}
requestAnimationFrame(()=>{ input.focus(); });
trapFocus();
}
function closeModal(){
if(!isOpen()) return;
modal.setAttribute('hidden','');
if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus();
}
function copyCurrent(){
try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); }
catch(e){ fallback(); }
}
function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} }
function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); }
function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); }
function bindShareButtons(){
document.querySelectorAll('.h-share').forEach(btn=>{
if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; }
});
}
bindShareButtons();
if(document.readyState==='loading'){
document.addEventListener('DOMContentLoaded', bindShareButtons);
} else {
requestAnimationFrame(bindShareButtons);
}
document.addEventListener('click', function(e){
const shareBtn=e.target.closest && e.target.closest('.h-share');
if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); }
}, true);
document.addEventListener('click', e=>{
if(e.target===modal) closeModal();
if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); }
if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); }
});
document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); });
function trapFocus(){
if(trapBound) return;
trapBound=true;
modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } });
}
if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); });
})();
</script><p>Get Geode running locally in minutes, from zero to executing your first GQL query.</p>
<h3 id="prerequisites" class="position-relative d-flex align-items-center group">
<span>Prerequisites</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="prerequisites"
aria-haspopup="dialog"
aria-label="Share link: Prerequisites">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="system-requirements" class="position-relative d-flex align-items-center group">
<span>System Requirements</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="system-requirements"
aria-haspopup="dialog"
aria-label="Share link: System Requirements">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Minimum</strong>:</p>
<ul>
<li>CPU: 2 cores</li>
<li>RAM: 4GB</li>
<li>Disk: 2GB free space</li>
</ul>
<p><strong>Recommended</strong>:</p>
<ul>
<li>CPU: 4+ cores</li>
<li>RAM: 8GB+</li>
<li>Disk: 10GB+ free space (SSD preferred)</li>
</ul>
<h4 id="supported-platforms" class="position-relative d-flex align-items-center group">
<span>Supported Platforms</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="supported-platforms"
aria-haspopup="dialog"
aria-label="Share link: Supported Platforms">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li><strong>Linux</strong>: Ubuntu 20.04+, Debian 11+, RHEL 8+, Arch Linux</li>
<li><strong>macOS</strong>: macOS 11+ (Big Sur or later), including Apple Silicon</li>
<li><strong>Windows</strong>: Windows 10+ with WSL2</li>
</ul>
<h3 id="installation-options" class="position-relative d-flex align-items-center group">
<span>Installation Options</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="installation-options"
aria-haspopup="dialog"
aria-label="Share link: Installation Options">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="option-1-install-by-operating-system" class="position-relative d-flex align-items-center group">
<span>Option 1: Install by Operating System</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="option-1-install-by-operating-system"
aria-haspopup="dialog"
aria-label="Share link: Option 1: Install by Operating System">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="docs-tabs mb-4">
<ul class="nav nav-tabs" id="tabs-1774880880974135328" role="tablist"><li class="nav-item" role="presentation">
<button
class="nav-link active"
id="tabs-1774880880974135328-tab-0-tab"
data-bs-toggle="tab"
data-bs-target="#tabs-1774880880974135328-tab-0"
type="button"
role="tab"
aria-controls="tabs-1774880880974135328-tab-0"
aria-selected="true"
>
Linux
</button>
</li><li class="nav-item" role="presentation">
<button
class="nav-link"
id="tabs-1774880880974135328-tab-1-tab"
data-bs-toggle="tab"
data-bs-target="#tabs-1774880880974135328-tab-1"
type="button"
role="tab"
aria-controls="tabs-1774880880974135328-tab-1"
aria-selected="false"
>
macOS
</button>
</li><li class="nav-item" role="presentation">
<button
class="nav-link"
id="tabs-1774880880974135328-tab-2-tab"
data-bs-toggle="tab"
data-bs-target="#tabs-1774880880974135328-tab-2"
type="button"
role="tab"
aria-controls="tabs-1774880880974135328-tab-2"
aria-selected="false"
>
Windows (WSL)
</button>
</li></ul>
<div class="tab-content border border-top-0 rounded-bottom p-3" id="tabs-1774880880974135328-content"><div
class="tab-pane fade show active"
id="tabs-1774880880974135328-tab-0"
role="tabpanel"
aria-labelledby="tabs-1774880880974135328-tab-0-tab"
>
<div class="docs-tabs mb-4">
<ul class="nav nav-tabs" id="tabs-1774880880972217292" role="tablist"><li class="nav-item" role="presentation">
<button
class="nav-link active"
id="tabs-1774880880972217292-tab-0-tab"
data-bs-toggle="tab"
data-bs-target="#tabs-1774880880972217292-tab-0"
type="button"
role="tab"
aria-controls="tabs-1774880880972217292-tab-0"
aria-selected="true"
>
Debian/Ubuntu
</button>
</li><li class="nav-item" role="presentation">
<button
class="nav-link"
id="tabs-1774880880972217292-tab-1-tab"
data-bs-toggle="tab"
data-bs-target="#tabs-1774880880972217292-tab-1"
type="button"
role="tab"
aria-controls="tabs-1774880880972217292-tab-1"
aria-selected="false"
>
RHEL/Fedora
</button>
</li><li class="nav-item" role="presentation">
<button
class="nav-link"
id="tabs-1774880880972217292-tab-2-tab"
data-bs-toggle="tab"
data-bs-target="#tabs-1774880880972217292-tab-2"
type="button"
role="tab"
aria-controls="tabs-1774880880972217292-tab-2"
aria-selected="false"
>
Generic
</button>
</li></ul>
<div class="tab-content border border-top-0 rounded-bottom p-3" id="tabs-1774880880972217292-content"><div
class="tab-pane fade show active"
id="tabs-1774880880972217292-tab-0"
role="tabpanel"
aria-labelledby="tabs-1774880880972217292-tab-0-tab"
>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Add GPG signing key</span>
</span></span><span class="line"><span class="cl">curl -fsSL https://apt.geodedb.com/geode.gpg <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> sudo gpg --dearmor -o /usr/share/keyrings/geode-archive-keyring.gpg
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add repository</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">"deb [signed-by=/usr/share/keyrings/geode-archive-keyring.gpg] https://apt.geodedb.com stable main"</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> sudo tee /etc/apt/sources.list.d/geode.list
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Install</span>
</span></span><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt install geode
</span></span></code></pre></div>
</div><div
class="tab-pane fade"
id="tabs-1774880880972217292-tab-1"
role="tabpanel"
aria-labelledby="tabs-1774880880972217292-tab-1-tab"
>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">curl -L -o geode.rpm https://gitlab.com/devnw/codepros/geode/geode/-/releases/latest/download/geode-linux-x86_64.rpm
</span></span><span class="line"><span class="cl">sudo rpm -i geode.rpm
</span></span></code></pre></div>
</div><div
class="tab-pane fade"
id="tabs-1774880880972217292-tab-2"
role="tabpanel"
aria-labelledby="tabs-1774880880972217292-tab-2-tab"
>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">curl -L -o geode-linux-amd64 https://gitlab.com/devnw/codepros/geode/geode/-/releases/latest/download/geode-linux-amd64
</span></span><span class="line"><span class="cl">chmod +x geode-linux-amd64
</span></span><span class="line"><span class="cl">sudo install -m <span class="m">0755</span> geode-linux-amd64 /usr/local/bin/geode
</span></span></code></pre></div>
</div></div>
</div>
</div><div
class="tab-pane fade"
id="tabs-1774880880974135328-tab-1"
role="tabpanel"
aria-labelledby="tabs-1774880880974135328-tab-1-tab"
>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Install via Homebrew (recommended)</span>
</span></span><span class="line"><span class="cl">brew install geodedb/geode/geode
</span></span></code></pre></div>
</div><div
class="tab-pane fade"
id="tabs-1774880880974135328-tab-2"
role="tabpanel"
aria-labelledby="tabs-1774880880974135328-tab-2-tab"
>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># PowerShell</span>
</span></span><span class="line"><span class="cl">wsl --install -d Ubuntu
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Inside Ubuntu (WSL)</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Add GPG signing key</span>
</span></span><span class="line"><span class="cl">curl -fsSL https://apt.geodedb.com/geode.gpg <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> sudo gpg --dearmor -o /usr/share/keyrings/geode-archive-keyring.gpg
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add repository</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">"deb [signed-by=/usr/share/keyrings/geode-archive-keyring.gpg] https://apt.geodedb.com stable main"</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> sudo tee /etc/apt/sources.list.d/geode.list
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Install</span>
</span></span><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt install geode
</span></span></code></pre></div>
</div></div>
</div>
<h4 id="option-2-docker" class="position-relative d-flex align-items-center group">
<span>Option 2: Docker</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="option-2-docker"
aria-haspopup="dialog"
aria-label="Share link: Option 2: Docker">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Quick start</strong> with Docker Compose:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">cd</span> geode
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Single-node deployment</span>
</span></span><span class="line"><span class="cl">make docker-up-singleton
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or distributed cluster</span>
</span></span><span class="line"><span class="cl">make docker-up-distributed
</span></span></code></pre></div><p><strong>Manual Docker run</strong>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Pull image (when available)</span>
</span></span><span class="line"><span class="cl">docker pull geodedb/geode:latest
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Run server</span>
</span></span><span class="line"><span class="cl">docker run -d <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> -p 3141:3141 <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> -v geode-data:/var/lib/geode <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> --name geode <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> geodedb/geode:latest serve --listen 0.0.0.0:3141
</span></span></code></pre></div><p><strong>Environment variables</strong> for Docker:</p>
<ul>
<li><code>LOG_LEVEL</code>: Set logging level (debug/info/warn/error)</li>
<li><code>GEODE_DATA_DIR</code>: Data directory path (default: <code>/var/lib/geode</code>)</li>
<li><code>GEODE_ADMIN_USERNAME</code>: Initial admin username</li>
<li><code>GEODE_DEFAULT_PASSWORD</code>: Initial admin password</li>
</ul>
<p>See <a
href="/docs/ops/deployment#docker"
>Docker Deployment</a>
for the full production stack (Vault, MinIO, Prometheus, Grafana, Loki, Nginx).</p>
<h4 id="option-3-build-from-source" class="position-relative d-flex align-items-center group">
<span>Option 3: Build from Source</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="option-3-build-from-source"
aria-haspopup="dialog"
aria-label="Share link: Option 3: Build from Source">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Requirements</strong>: Zig 0.1.0+ (<a
href="https://ziglang.org/download/"
aria-label="download from ziglang.org – opens in new window"
target="_blank" rel="noopener noreferrer"
>download from ziglang.org
<span aria-hidden="true" class="external-icon">↗</span>
</a>
)</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Clone repository</span>
</span></span><span class="line"><span class="cl">git clone https://github.com/codeprosorg/geode
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> geode
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Debug build (faster compilation)</span>
</span></span><span class="line"><span class="cl">make build
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or release build (optimized, recommended for production)</span>
</span></span><span class="line"><span class="cl">make release
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify installation</span>
</span></span><span class="line"><span class="cl">geode --version
</span></span></code></pre></div><p><strong>Make targets</strong> (from <code>QUICK_REFERENCE.md</code>):</p>
<ul>
<li><code>make build</code> - Debug build with symbols</li>
<li><code>make release</code> - ReleaseSafe build (recommended)</li>
<li><code>make test</code> - Run core unit tests</li>
<li><code>make geodetestlab-comprehensive</code> - Full test suite (97.4% pass rate)</li>
</ul>
<p>For detailed build options, see <a
href="/docs/installation/from-source"
>Install from Source</a>
.</p>
<h3 id="start-the-server" class="position-relative d-flex align-items-center group">
<span>Start the Server</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="start-the-server"
aria-haspopup="dialog"
aria-label="Share link: Start the Server">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="default-server-start" class="position-relative d-flex align-items-center group">
<span>Default Server Start</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="default-server-start"
aria-haspopup="dialog"
aria-label="Share link: Default Server Start">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Start with defaults (QUIC/TLS on port 3141)</span>
</span></span><span class="line"><span class="cl">./geode serve
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or if installed system-wide</span>
</span></span><span class="line"><span class="cl">geode serve
</span></span></code></pre></div><p><strong>Default behavior</strong>:</p>
<ul>
<li>Listens on <code>127.0.0.1:3141</code> (QUIC+TLS only, no TCP)</li>
<li>Data directory: <code>./geode-data</code> (current directory)</li>
<li>Auto-generates self-signed certificates if none provided</li>
<li>Creates default admin user if <code>GEODE_ADMIN_USERNAME</code> / <code>GEODE_DEFAULT_PASSWORD</code> env vars are set</li>
</ul>
<h4 id="custom-server-start" class="position-relative d-flex align-items-center group">
<span>Custom Server Start</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="custom-server-start"
aria-haspopup="dialog"
aria-label="Share link: Custom Server Start">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Custom listen address and data directory</span>
</span></span><span class="line"><span class="cl">./geode serve --listen 0.0.0.0:8443 --data-dir /var/lib/geode
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># With TLS certificates (production)</span>
</span></span><span class="line"><span class="cl">./geode serve <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> --listen 0.0.0.0:3141 <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> --cert /etc/geode/certs/server-cert.pem <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> --key /etc/geode/certs/server-key.pem <span class="se">\
</span></span></span><span class="line"><span class="cl"><span class="se"></span> --data-dir /var/lib/geode
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># With configuration file</span>
</span></span><span class="line"><span class="cl">./geode serve --config /etc/geode/geode.yaml
</span></span></code></pre></div><p><strong>Example configuration</strong> (<code>geode.yaml</code> from <code>USAGE.md</code>):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">server</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">listen</span><span class="p">:</span><span class="w"> </span><span class="s1">'0.0.0.0:3141'</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">data_dir</span><span class="p">:</span><span class="w"> </span><span class="s1">'/var/lib/geode'</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nt">tls</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">cert</span><span class="p">:</span><span class="w"> </span><span class="s1">'/etc/geode/certs/server-cert.pem'</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">key</span><span class="p">:</span><span class="w"> </span><span class="s1">'/etc/geode/certs/server-key.pem'</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nt">storage</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">page_size</span><span class="p">:</span><span class="w"> </span><span class="m">8192</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">page_cache_size</span><span class="p">:</span><span class="w"> </span><span class="s1">'1GB'</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nt">logging</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">level</span><span class="p">:</span><span class="w"> </span><span class="s1">'info'</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">format</span><span class="p">:</span><span class="w"> </span><span class="s1">'json'</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nt">security</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">tde</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"> </span><span class="nt">key_hex</span><span class="p">:</span><span class="w"> </span><span class="s1">'0123456789abcdef...'</span><span class="w"> </span><span class="c"># 32-byte hex key for AES-256-GCM</span><span class="w">
</span></span></span></code></pre></div>
<h3 id="connect-and-run-your-first-query" class="position-relative d-flex align-items-center group">
<span>Connect and Run Your First Query</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="connect-and-run-your-first-query"
aria-haspopup="dialog"
aria-label="Share link: Connect and Run Your First Query">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="using-the-client-cli" class="position-relative d-flex align-items-center group">
<span>Using the Client CLI</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="using-the-client-cli"
aria-haspopup="dialog"
aria-label="Share link: Using the Client CLI">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Execute a single query</span>
</span></span><span class="line"><span class="cl">geode query <span class="s2">"RETURN 1 AS x"</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Execute from file</span>
</span></span><span class="line"><span class="cl">geode query -f query.gql
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Choose output format</span>
</span></span><span class="line"><span class="cl">geode query --format json <span class="s2">"MATCH (n) RETURN n LIMIT 10"</span>
</span></span><span class="line"><span class="cl">geode query --format txt <span class="s2">"MATCH (n) RETURN n LIMIT 10"</span>
</span></span></code></pre></div><p><strong>Output formats</strong> (from <code>USAGE.md</code>):</p>
<ul>
<li><code>txt</code> - Human-readable table format (default)</li>
<li><code>json</code> - JSON lines (one object per row)</li>
</ul>
<h4 id="using-the-interactive-shell" class="position-relative d-flex align-items-center group">
<span>Using the Interactive Shell</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="using-the-interactive-shell"
aria-haspopup="dialog"
aria-label="Share link: Using the Interactive Shell">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Start the REPL</strong>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Start interactive shell</span>
</span></span><span class="line"><span class="cl">./geode shell
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or the alternative entrypoint</span>
</span></span><span class="line"><span class="cl">./gql
</span></span></code></pre></div><p><strong>Key meta commands</strong> (from <code>REPL_USAGE.md</code>):</p>
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>\connect <uri></code></td>
<td>Connect to a server</td>
</tr>
<tr>
<td><code>\begin</code></td>
<td>Start transaction</td>
</tr>
<tr>
<td><code>\commit</code></td>
<td>Commit transaction</td>
</tr>
<tr>
<td><code>\rollback</code></td>
<td>Rollback transaction</td>
</tr>
<tr>
<td><code>\format json|txt</code></td>
<td>Set output format</td>
</tr>
<tr>
<td><code>\timing on|off</code></td>
<td>Show query execution time</td>
</tr>
<tr>
<td><code>\help</code></td>
<td>Show help</td>
</tr>
<tr>
<td><code>\quit</code></td>
<td>Exit shell</td>
</tr>
</tbody>
</table>
<p><strong>Example session</strong>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql"><span class="line"><span class="cl"><span class="err">--</span><span class="w"> </span><span class="py">Connect</span><span class="w"> </span><span class="py">to</span><span class="w"> </span><span class="py">server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">\</span><span class="py">connect</span><span class="w"> </span><span class="py">quic</span><span class="p">:</span><span class="err">//</span><span class="nc">localhost</span><span class="p">:</span><span class="nc">3141</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">--</span><span class="w"> </span><span class="py">Create</span><span class="w"> </span><span class="py">a</span><span class="w"> </span><span class="py">graph</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="py">CREATE</span><span class="w"> </span><span class="py">GRAPH</span><span class="w"> </span><span class="py">SocialNetwork</span><span class="err">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="py">USE</span><span class="w"> </span><span class="py">SocialNetwork</span><span class="err">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">--</span><span class="w"> </span><span class="py">Create</span><span class="w"> </span><span class="py">nodes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="py">CREATE</span><span class="w"> </span><span class="p">(:</span><span class="nc">Person</span><span class="w"> </span><span class="p">{</span><span class="py">name</span><span class="p">:</span><span class="w"> </span><span class="s">"Alice"</span><span class="p">,</span><span class="w"> </span><span class="nc">age</span><span class="p">:</span><span class="w"> </span><span class="nc">30</span><span class="p">})</span><span class="err">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="py">CREATE</span><span class="w"> </span><span class="p">(:</span><span class="nc">Person</span><span class="w"> </span><span class="p">{</span><span class="py">name</span><span class="p">:</span><span class="w"> </span><span class="s">"Bob"</span><span class="p">,</span><span class="w"> </span><span class="nc">age</span><span class="p">:</span><span class="w"> </span><span class="nc">25</span><span class="p">})</span><span class="err">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">--</span><span class="w"> </span><span class="py">Create</span><span class="w"> </span><span class="py">relationship</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="py">MATCH</span><span class="w"> </span><span class="p">(</span><span class="py">a</span><span class="p">:</span><span class="nc">Person</span><span class="w"> </span><span class="p">{</span><span class="py">name</span><span class="p">:</span><span class="w"> </span><span class="s">"Alice"</span><span class="p">}),</span><span class="w"> </span><span class="p">(</span><span class="nc">b</span><span class="p">:</span><span class="nc">Person</span><span class="w"> </span><span class="p">{</span><span class="py">name</span><span class="p">:</span><span class="w"> </span><span class="s">"Bob"</span><span class="p">})</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nc">CREATE</span><span class="w"> </span><span class="p">(</span><span class="py">a</span><span class="p">)</span><span class="err">-</span><span class="p">[:</span><span class="nc">KNOWS</span><span class="w"> </span><span class="p">{</span><span class="py">since</span><span class="p">:</span><span class="w"> </span><span class="nc">2020</span><span class="p">}]</span><span class="err">-></span><span class="p">(</span><span class="py">b</span><span class="p">)</span><span class="err">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">--</span><span class="w"> </span><span class="py">Query</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="py">MATCH</span><span class="w"> </span><span class="p">(</span><span class="py">p</span><span class="p">:</span><span class="nc">Person</span><span class="p">)</span><span class="err">-</span><span class="p">[</span><span class="py">k</span><span class="p">:</span><span class="nc">KNOWS</span><span class="p">]</span><span class="err">-></span><span class="p">(</span><span class="py">friend</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="py">RETURN</span><span class="w"> </span><span class="py">p</span><span class="err">.</span><span class="py">name</span><span class="p">,</span><span class="w"> </span><span class="py">friend</span><span class="err">.</span><span class="py">name</span><span class="p">,</span><span class="w"> </span><span class="py">k</span><span class="err">.</span><span class="py">since</span><span class="err">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">--</span><span class="w"> </span><span class="py">Enable</span><span class="w"> </span><span class="py">timing</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">\</span><span class="py">timing</span><span class="w"> </span><span class="kd">on</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">--</span><span class="w"> </span><span class="py">Run</span><span class="w"> </span><span class="py">EXPLAIN</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="py">EXPLAIN</span><span class="w"> </span><span class="py">MATCH</span><span class="w"> </span><span class="p">(</span><span class="py">p</span><span class="p">:</span><span class="nc">Person</span><span class="p">)</span><span class="w"> </span><span class="py">RETURN</span><span class="w"> </span><span class="py">p</span><span class="err">.</span><span class="py">name</span><span class="err">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">--</span><span class="w"> </span><span class="py">Start</span><span class="w"> </span><span class="py">transaction</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">\</span><span class="py">begin</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">--</span><span class="w"> </span><span class="py">Make</span><span class="w"> </span><span class="py">changes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="py">CREATE</span><span class="w"> </span><span class="p">(:</span><span class="nc">Person</span><span class="w"> </span><span class="p">{</span><span class="py">name</span><span class="p">:</span><span class="w"> </span><span class="s">"Charlie"</span><span class="p">,</span><span class="w"> </span><span class="nc">age</span><span class="p">:</span><span class="w"> </span><span class="nc">35</span><span class="p">})</span><span class="err">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">--</span><span class="w"> </span><span class="py">Commit</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="err">\</span><span class="py">commit</span><span class="w">
</span></span></span></code></pre></div>
<h3 id="troubleshooting" class="position-relative d-flex align-items-center group">
<span>Troubleshooting</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="troubleshooting"
aria-haspopup="dialog"
aria-label="Share link: Troubleshooting">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="tlscertificate-issues" class="position-relative d-flex align-items-center group">
<span>TLS/Certificate Issues</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="tlscertificate-issues"
aria-haspopup="dialog"
aria-label="Share link: TLS/Certificate Issues">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Symptom</strong>: “certificate verification failed” or “TLS handshake failed”</p>
<p><strong>Solution</strong>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verify certificate</span>
</span></span><span class="line"><span class="cl">openssl x509 -in /etc/geode/certs/server-cert.pem -text -noout
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check certificate matches key</span>
</span></span><span class="line"><span class="cl">openssl x509 -noout -modulus -in server-cert.pem <span class="p">|</span> openssl md5
</span></span><span class="line"><span class="cl">openssl rsa -noout -modulus -in server-key.pem <span class="p">|</span> openssl md5
</span></span><span class="line"><span class="cl"><span class="c1"># Should match</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># For development, use self-signed cert</span>
</span></span><span class="line"><span class="cl">./geode serve <span class="c1"># Auto-generates if none present</span>
</span></span></code></pre></div>
<h4 id="port-binding-issues" class="position-relative d-flex align-items-center group">
<span>Port Binding Issues</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="port-binding-issues"
aria-haspopup="dialog"
aria-label="Share link: Port Binding Issues">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Symptom</strong>: “address already in use” or “bind failed”</p>
<p><strong>Solution</strong>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Find process using port</span>
</span></span><span class="line"><span class="cl">lsof -i :3141
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Kill process</span>
</span></span><span class="line"><span class="cl"><span class="nb">kill</span> -9 <PID>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or use different port</span>
</span></span><span class="line"><span class="cl">./geode serve --listen 0.0.0.0:3142
</span></span></code></pre></div>
<h4 id="connection-issues" class="position-relative d-flex align-items-center group">
<span>Connection Issues</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="connection-issues"
aria-haspopup="dialog"
aria-label="Share link: Connection Issues">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Symptom</strong>: “connection refused” or “cannot connect”</p>
<p><strong>Checklist</strong>:</p>
<ol>
<li>
<p><strong>Server running?</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ps aux <span class="p">|</span> grep geode
</span></span></code></pre></div></li>
<li>
<p><strong>Correct port?</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check server logs for listening address</span>
</span></span></code></pre></div></li>
<li>
<p><strong>Firewall blocking?</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check firewall rules</span>
</span></span><span class="line"><span class="cl">sudo ufw status <span class="c1"># Ubuntu/Debian</span>
</span></span><span class="line"><span class="cl">sudo firewall-cmd --list-all <span class="c1"># RHEL/CentOS</span>
</span></span></code></pre></div></li>
<li>
<p><strong>QUIC support?</strong></p>
<ul>
<li>Geode requires QUIC (UDP transport). Ensure UDP port 3141 is open, not just TCP.</li>
</ul>
</li>
</ol>
<h3 id="next-steps" class="position-relative d-flex align-items-center group">
<span>Next Steps</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="next-steps"
aria-haspopup="dialog"
aria-label="Share link: Next Steps">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><p>Now that Geode is running:</p>
<ul>
<li><strong><a
href="/docs/gql/guide"
>GQL Guide</a>
</strong> - Learn the query language with examples</li>
<li><strong><a
href="/docs/model/data-model-and-types"
>Data Model and Types</a>
</strong> - Understand property graphs and types</li>
<li><strong><a
href="/docs/configuration"
>Configuration Reference</a>
</strong> - Deep dive into server configuration</li>
<li><strong><a
href="/docs/client-libraries"
>Client Libraries</a>
</strong> - Connect from Go, Python, Rust, or Zig</li>
<li><strong><a
href="/docs/ops/deployment"
>Deployment Guide</a>
</strong> - Production deployment patterns (Vault, MinIO, Prometheus, Grafana, Loki)</li>
</ul>
<h4 id="health-and-monitoring" class="position-relative d-flex align-items-center group">
<span>Health and Monitoring</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="health-and-monitoring"
aria-haspopup="dialog"
aria-label="Share link: Health and Monitoring">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>Once running, check server health:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Health check endpoint</span>
</span></span><span class="line"><span class="cl">curl http://localhost:8080/health
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Readiness check</span>
</span></span><span class="line"><span class="cl">curl http://localhost:8080/ready
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Prometheus metrics</span>
</span></span><span class="line"><span class="cl">curl http://localhost:8080/metrics
</span></span></code></pre></div><p>See <a
href="/docs/ops/observability"
>Monitoring and Telemetry</a>
for full observability setup.</p>
Installation and Quick Start
Install Geode via OS packages, Docker, or source; start the QUIC/TLS server; connect with CLI/REPL; run your first GQL query