fkrebs/docs
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b68ab51e0ed4389b989fd21f063244f0aabb2560
docs/stacks/nexa/CLAUDE/index.html
T

1977 lines
41 KiB
HTML
Raw Blame History

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="Single source of truth for the homelab">
<link rel="canonical" href="http://192.168.1.8:13080/stacks/nexa/CLAUDE/">
<link rel="icon" href="../../../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
<title>CLAUDE - nuclide.systems docs</title>
<link rel="stylesheet" href="../../../assets/stylesheets/main.484c7ddc.min.css">
<link rel="stylesheet" href="../../../assets/stylesheets/palette.ab4e12ef.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr" data-md-color-scheme="slate" data-md-color-primary="black" data-md-color-accent="blue">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#instructions-for-claude-and-other-agents" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../../.." title="nuclide.systems docs" class="md-header__button md-logo" aria-label="nuclide.systems docs" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
nuclide.systems docs
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
CLAUDE
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="black" data-md-color-accent="blue" aria-hidden="true" type="radio" name="__palette" id="__palette_0">
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="black" data-md-color-accent="blue" aria-hidden="true" type="radio" name="__palette" id="__palette_1">
</form>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
<div class="md-search__suggest" data-md-component="search-suggest"></div>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href="../../.." class="md-tabs__link">
Home
</a>
</li>
<li class="md-tabs__item">
<a href="../../../CHANGELOG/" class="md-tabs__link">
Changelog
</a>
</li>
<li class="md-tabs__item">
<a href="../../../RESUME/" class="md-tabs__link">
Resume
</a>
</li>
<li class="md-tabs__item">
<a href="../../../ct-inventory/" class="md-tabs__link">
CT inventory
</a>
</li>
<li class="md-tabs__item">
<a href="../../../infra/proxmox-state/" class="md-tabs__link">
Infra
</a>
</li>
<li class="md-tabs__item">
<a href="../../../services/homelab-architecture/" class="md-tabs__link">
Services
</a>
</li>
<li class="md-tabs__item">
<a href="../../../security/data-leak-audit-comparison/" class="md-tabs__link">
Security & audits
</a>
</li>
<li class="md-tabs__item">
<a href="../../../ideas/stack-ideas/" class="md-tabs__link">
Ideas
</a>
</li>
<li class="md-tabs__item">
<a href="../../../history/traefik-migration/" class="md-tabs__link">
History
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../../.." title="nuclide.systems docs" class="md-nav__button md-logo" aria-label="nuclide.systems docs" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
</a>
nuclide.systems docs
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../.." class="md-nav__link">
<span class="md-ellipsis">
Home
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../CHANGELOG/" class="md-nav__link">
<span class="md-ellipsis">
Changelog
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../RESUME/" class="md-nav__link">
<span class="md-ellipsis">
Resume
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../ct-inventory/" class="md-nav__link">
<span class="md-ellipsis">
CT inventory
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_5" >
<label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0">
<span class="md-ellipsis">
Infra
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
Infra
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../infra/proxmox-state/" class="md-nav__link">
<span class="md-ellipsis">
Proxmox state
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../infra/portmap/" class="md-nav__link">
<span class="md-ellipsis">
Port map
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../infra/storage/" class="md-nav__link">
<span class="md-ellipsis">
Storage
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../infra/volumes/" class="md-nav__link">
<span class="md-ellipsis">
Volumes
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../infra/docker-networks/" class="md-nav__link">
<span class="md-ellipsis">
Docker networks
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../infra/connection-hosts/" class="md-nav__link">
<span class="md-ellipsis">
Connection hosts
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../infra/proxmox-memory-audit/" class="md-nav__link">
<span class="md-ellipsis">
Memory audit
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_6" >
<label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0">
<span class="md-ellipsis">
Services
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_6">
<span class="md-nav__icon md-icon"></span>
Services
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../services/homelab-architecture/" class="md-nav__link">
<span class="md-ellipsis">
Homelab architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/dev-environment/" class="md-nav__link">
<span class="md-ellipsis">
Dev environment (Coder + Gitea)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/mcp-gateway/" class="md-nav__link">
<span class="md-ellipsis">
MCP gateway
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/mcp-servers/" class="md-nav__link">
<span class="md-ellipsis">
MCP servers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/pocket-id/" class="md-nav__link">
<span class="md-ellipsis">
Pocket-ID (OIDC)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/backrest/" class="md-nav__link">
<span class="md-ellipsis">
Backrest (backups)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/databases/" class="md-nav__link">
<span class="md-ellipsis">
Databases
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/secrets-manager/" class="md-nav__link">
<span class="md-ellipsis">
Secrets manager
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/comfyui/" class="md-nav__link">
<span class="md-ellipsis">
ComfyUI
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/zoraxy/" class="md-nav__link">
<span class="md-ellipsis">
Zoraxy
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/adguard-dns/" class="md-nav__link">
<span class="md-ellipsis">
AdGuard DNS
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/cloud-gpu/" class="md-nav__link">
<span class="md-ellipsis">
Cloud GPU
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/arcane/" class="md-nav__link">
<span class="md-ellipsis">
Arcane
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/doc-ingestion/" class="md-nav__link">
<span class="md-ellipsis">
Doc ingestion pipeline
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../services/llm-benchmark/" class="md-nav__link">
<span class="md-ellipsis">
LLM benchmark
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_7" >
<label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0">
<span class="md-ellipsis">
Security & audits
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_7">
<span class="md-nav__icon md-icon"></span>
Security & audits
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../security/data-leak-audit-comparison/" class="md-nav__link">
<span class="md-ellipsis">
Comparison
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../security/data-leak-audit-2026-05-20-tr004-cloud-sandbox/" class="md-nav__link">
<span class="md-ellipsis">
2026-05-20 · cloud-sandbox breach
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../security/data-leak-audit-2026-05-21-tr004-artifacts/" class="md-nav__link">
<span class="md-ellipsis">
2026-05-21 · artifacts (clean)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../security/audit-claude-code-meta/" class="md-nav__link">
<span class="md-ellipsis">
Self-audit (Claude Code)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../security/transcripts/audit-chat-2026-05-21/" class="md-nav__link">
<span class="md-ellipsis">
Transcript (audit session)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_8" >
<label class="md-nav__link" for="__nav_8" id="__nav_8_label" tabindex="0">
<span class="md-ellipsis">
Ideas
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_8">
<span class="md-nav__icon md-icon"></span>
Ideas
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../ideas/stack-ideas/" class="md-nav__link">
<span class="md-ellipsis">
Stack ideas
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_9" >
<label class="md-nav__link" for="__nav_9" id="__nav_9_label" tabindex="0">
<span class="md-ellipsis">
History
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_9">
<span class="md-nav__icon md-icon"></span>
History
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../history/traefik-migration/" class="md-nav__link">
<span class="md-ellipsis">
Traefik (abandoned 2026-05-16)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../history/traefik-migration-docker-labels/" class="md-nav__link">
<span class="md-ellipsis">
Traefik labels (abandoned)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../history/mcp-gateway-requirements/" class="md-nav__link">
<span class="md-ellipsis">
MCP gateway requirements (superseded)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../history/scrubbing-list-2026-05-17/" class="md-nav__link">
<span class="md-ellipsis">
Scrubbing list (2026-05-17)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../history/case-study/" class="md-nav__link">
<span class="md-ellipsis">
Case study
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#repo-conventions" class="md-nav__link">
<span class="md-ellipsis">
Repo conventions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#real-infrastructure-verified-from-screenshots-may-2026" class="md-nav__link">
<span class="md-ellipsis">
Real infrastructure (verified from screenshots, May 2026)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#when-working-on-nexa" class="md-nav__link">
<span class="md-ellipsis">
When working on Nexa
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#branch-policy" class="md-nav__link">
<span class="md-ellipsis">
Branch policy
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#quick-links" class="md-nav__link">
<span class="md-ellipsis">
Quick links
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<blockquote>
<p><strong>STATUS: STALE — many claims (PVE version, Pocket-ID port, Dockge as docker manager) no longer accurate. Source of truth is /CLAUDE.md and /docs/services/. This file kept for the original nexa-stack design notes only.</strong></p>
</blockquote>
<hr />
<h1 id="instructions-for-claude-and-other-agents">Instructions for Claude (and other agents)<a class="headerlink" href="#instructions-for-claude-and-other-agents" title="Permanent link">&para;</a></h1>
<p>This file tells future automated runs what they need to know about this repo.</p>
<h2 id="repo-conventions">Repo conventions<a class="headerlink" href="#repo-conventions" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Documentation:</strong> all docs live in <code>/docs/</code> and are numbered. Entry point is <code>docs/index.md</code>. When you add a doc, give it the next free <code>NN-</code> prefix and add a row to the index TOC.</li>
<li><strong>Runtime artifacts:</strong> live in <code>nexa-core/</code> (workflows, prompts, configs, scripts). Don't put <code>.md</code> documentation in there — link from <code>/docs/</code> instead.</li>
<li><strong>Source-of-truth:</strong> if a doc duplicates content from <code>nexa-core/config/*.md</code>, <strong>delete the duplicate</strong>. Single source of truth.</li>
</ul>
<h2 id="real-infrastructure-verified-from-screenshots-may-2026">Real infrastructure (verified from screenshots, May 2026)<a class="headerlink" href="#real-infrastructure-verified-from-screenshots-may-2026" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Proxmox host</strong> <code>nuc</code> at <code>192.168.1.20:8006</code> (PVE 9.1.9, kernel 6.17.13-4-pve, EFI).</li>
<li>Hardware: <strong>22 threads</strong> (Intel Core Ultra 7 155H, 1 socket), <strong>62 GiB RAM</strong>, <strong>1.64 TiB disk</strong>.</li>
<li>Steady state: ~32 GiB used (≈24 GiB of which is ZFS ARC, tunable via <code>zfs_arc_max</code>), CPU load &lt;2.0, IO delay &lt;0.05%.</li>
<li>LXC 102 dns (AdGuard) — internal DNS, rewrites for <code>*.nuclide.systems</code>.</li>
<li>LXC 103 backrest — backup orchestration.</li>
<li>LXC 104 docker — main docker host at <code>192.168.1.40</code>, hostname <code>docker</code>, OS Debian 13. <strong>Unprivileged</strong>, originally provisioned from the Dockge helper-script template, but <strong>Arcane is the active docker manager</strong> today (Dockge is stale, slated for retirement — see <a href="../docs/12-optimization-opportunities/#33">docs/12 #33</a>). <strong>Dozzle</strong> is the live log viewer. Allocated: 16 CPU, 31.25 GiB RAM (25% used), 8 GiB swap, 200 GiB boot disk (47.7% used). <strong>Storage = Ubiquiti UNAS Pro at <code>192.168.1.31</code></strong> (UniFi Drive 4.1.16 on UniFi OS 5.0.17, SFP+ 10 GbE, RAID 6, 19.96 TiB raw / 2.05 TiB used). NFS-exported at <code>/var/nfs/shared/storage</code>, mounted by Proxmox at <code>/mnt/pve/unas</code>, also exposed via SMB at <code>smb://192.168.1.31/&lt;share&gt;</code> (Mac) / <code>\\192.168.1.31\&lt;share&gt;</code> (Win).</li>
</ul>
<p><strong>Standard pattern for docker volumes (verified via Karakeep, Q19): plain host bind-mount of <code>/mnt/pve/unas/services/&lt;svc&gt;/&lt;vol&gt;</code> from inside LXC 104.</strong> No <code>driver_opts</code>, no CIFS, no credentials in the compose. Karakeep, Immich and the rest do exactly this. Nexa follows suit. SMB-as-docker-volume is documented as an <strong>escape hatch only</strong> (<a href="../docs/12-optimization-opportunities/#27">docs/12 #27</a>) for services that hit Nextcloud-style NFS issues — Nexa doesn't, so we don't use it.</p>
<p><strong>Storage-layer snapshots are NOT configured</strong> on UNAS Pool 1 ("Click to Setup" in the UniFi Drive dashboard). All 2 TB of homelab data has no point-in-time protection at the storage layer — Backrest covers files, not "the whole pool last Tuesday". Highest-leverage fix in the homelab right now (<a href="../docs/12-optimization-opportunities/#38">docs/12 #38</a>).</p>
<p><strong>UNAS layout conventions</strong> (homelab-wide, all docker containers follow them):
- <strong><code>services/&lt;svc&gt;/</code> is the general docker config store</strong> — every container in LXC 104 binds its persistent data here. Existing tenants observed: immich, karakeep, nextcloud, ntfy, paperless-ai, pocketid, shelfmark, stremio, traccar, vaultwarden, gluetun. <strong>Stale (retire, do not consume):</strong> <code>services/siyuan/</code> (migrated to Obsidian), <code>services/open-webui/</code> (unused — LobeHub is the active LLM UI), and <code>services/dockge/</code> if it exists (retired in favor of Arcane). <strong>Nexa MUST follow the same pattern: <code>services/nexa/{qdrant,tei-cache,graphdb,...}</code>.</strong> Don't invent a parallel layout.
- <code>backup/&lt;svc&gt;/</code> — per-service backups (existing: home-assistant tars, immich pgdump, nextcloud borg). <strong>Nexa snapshots → <code>backup/nexa/</code>.</strong>
- <code>media/</code>, <code>code/</code>, <code>_sortMe/</code>, <code>dump/</code>, <code>test_perm</code> — user data, not Nexa's concern.
- <strong>Before deploying any Nexa container, READ AN EXISTING STACK</strong> in <strong>Arcane</strong> (e.g. <code>karakeep</code> or <code>immich</code>) to confirm the exact mount syntax in use — driver name, share path, credential injection pattern. Match it. The actual NFS export root is <code>/var/nfs/shared/storage</code>; the SMB share name is <strong>still TBD — see Q19</strong> in <code>docs/11</code>.</p>
<p><strong>Hard-blocklist for any Nexa indexer / agent</strong> (never read these paths or matching glob):
- <code>_sortMe/wallet/**</code> — contains PGP keys + bitcoin wallet files.
- Any path matching <code>*.gpg</code>, <code>*.asc</code>, <code>*.key</code>, <code>*.pem</code>, <code>id_rsa*</code>, <code>*wallet*</code>, <code>*.kdbx</code>, <code>*credentials*</code>, <code>*secret*</code>.
- The Nextcloud appdata dir (<code>services/nextcloud/appdata_*</code>) — Nextcloud-internal, not user content. Intel iGPU passthrough is <em>configured but currently broken</em> — see <a href="../docs/12-optimization-opportunities/#26">docs/12 #26</a>.
- LXC 105 nextcloud — Nextcloud at <code>nc.nuclide.systems</code>.
- LXC 106 octoprint — currently <em>Exited</em>; flagged in <a href="../docs/11-open-questions/#q13">docs/11</a>.
- LXC 108 zoraxy — reverse proxy at <code>192.168.1.4:8000</code>, TLS for <code>*.nuclide.systems</code>.
- VM 100 haos — Home Assistant.
- <strong>Already-running services on docker host</strong> (don't redeploy):
- Memos <code>:5230</code>, n8n <code>:5678</code>, LiteLLM <code>:4000</code> (UI LobeHub <code>:3210</code>), Qdrant (<code>qdrant_scientific</code>), ntfy <code>:7998</code>, Karakeep (legacy alias <code>hoarder.nuclide.systems</code>), Vaultwarden <code>:11001</code>, Pocket-ID <code>:1411</code>, Immich, Audiobookshelf, Paperless-ngx, Traccar, Prowlarr, plus MCP containers (<code>crawl4ai-mcp</code>, <code>markitdown-mcp</code>, <code>papersearch-mcp</code>).
- <strong>Octoprint (LXC 106)</strong> is <em>intentionally</em> powered down most of the time. Phase-5 monitoring must skip names matching <code>octoprint*</code> rather than alert on its Exited state.
- <strong>Obsidian vault lives inside Nextcloud</strong> at <code>nc.nuclide.systems/Notizen/</code> (multi-device sync via Nextcloud client). Nexa accesses it via WebDAV — read-only, no filesystem mount. Ignore list: <code>.copilot/</code>, <code>.copilot-index/</code>, <code>.smart-env/</code>, <code>.caldav-sync/</code>, <code>assets/</code> (visual queue, Phase 3.2), <code>Templates/</code>, <code>BMO/</code>, <code>Excalidraw/</code>. Index target: <code>Notizen/**/*.md</code>.
- <strong>Nextcloud Tasks lists &amp; calendars</strong> (German names, may grow over time):
- <code>Persönlich</code> → Personal context.
- <code>DLR</code> → Work context (DLR is the user's employer).
- <code>Einkaufsliste</code> → Shopping.
- <code>Wunschliste</code> → Wishes.
Lists are discovered <strong>by name</strong> at runtime (Qdrant <code>_config</code> namespace caches <code>name → id</code>). Never hardcode IDs. The discovery workflow runs daily and on cache-miss; new lists added in Nextcloud are honoured automatically next refresh.
- <strong>Mail = Nextcloud Mail, single account <code>fkrebs@nucli.de</code>.</strong> No separate IMAP entry. The <code>Waiting</code> folder is a manual user signal — items there are skipped from digests.
- <strong>Backup model is 3-2-1</strong>: UNAS native snapshots → <code>s3.nuclide.systems</code> (warm, on-site) → encrypted off-site cold tier (provider TBD, Jottacloud is the user's candidate — see <a href="../docs/11-open-questions/#q20">Q20</a>). Always <code>restic</code>/<code>rclone-crypt</code> before upload — third-party provider sees only ciphertext. Don't propose alternative backup paths without checking docs/12 #37 first.
- <strong>Auth = Pocket-ID SSO is global</strong> at the Zoraxy layer. Don't add app-level basic-auth to Nexa surfaces; UIs inherit SSO. Machine-to-machine still uses API keys / app passwords.
- <strong>Decided for Nexa</strong> (don't re-litigate without user input):
- Vector store: <strong>reuse <code>qdrant_scientific</code></strong> with collections suffixed by modality (<code>nexa_knowledge_text</code>, <code>nexa_knowledge_visual</code>).
- Embeddings staged: <strong>Phase 3.1</strong> TEI + <code>BAAI/bge-m3</code> (text-only, 1024-dim). <strong>Phase 3.2</strong> swap to <code>infinity</code> and add <code>jinaai/jina-clip-v2</code> (768-dim, joint text+image space). All forward-compat fields (<code>modality</code>, <code>media_uri</code>, <code>graph_iri</code>, <code>nexa:pendingVisualIndex</code>) exist from 3.1 — adding the visual collection is additive.
- Graph store: <strong>Ontotext GraphDB</strong> (SPARQL/RDF), Phase 3.4. RDF schema in docs/08 already includes <code>nexa:modality</code> / <code>nexa:mediaUri</code> / <code>nexa:vectorCollection</code> / <code>nexa:pendingVisualIndex</code>.
- Chat model: SAIA via LiteLLM virtual key.</p>
<h2 id="when-working-on-nexa">When working on Nexa<a class="headerlink" href="#when-working-on-nexa" title="Permanent link">&para;</a></h2>
<ol>
<li><strong>Read <code>docs/index.md</code> first</strong> — it's the navigator.</li>
<li><strong>Open questions first.</strong> Before writing code or workflow JSON, scan <code>docs/11-open-questions.md</code>. If your task touches an unanswered Q, <strong>stop and ask</strong> rather than picking a default. Append new blockers to that doc as <code>[ ] Q-NN</code>.</li>
<li><strong>Optimization findings.</strong> When you spot infrastructure improvements, add them to <code>docs/12-optimization-opportunities.md</code> as a numbered bullet — don't just mention them in commit messages.</li>
<li><strong>Never inline secrets</strong> in workflow JSON or <code>.env</code> committed to git. Use n8n credentials, LiteLLM virtual keys, or (longer term) Vaultwarden.</li>
<li><strong>Keep deployment minimal.</strong> The default answer to <em>"do we need a new container?"</em> is <strong>no</strong> — the existing stack covers most needs.</li>
</ol>
<h2 id="branch-policy">Branch policy<a class="headerlink" href="#branch-policy" title="Permanent link">&para;</a></h2>
<ul>
<li>This branch is <code>claude/organize-docs-deployment-7N4v2</code>. Push only here unless told otherwise.</li>
<li>New work for an unrelated feature → new branch under <code>claude/&lt;topic&gt;</code>.</li>
</ul>
<h2 id="quick-links">Quick links<a class="headerlink" href="#quick-links" title="Permanent link">&para;</a></h2>
<ul>
<li><a href="../docs/">docs/index.md</a></li>
<li><a href="../docs/09-deployment/">docs/09-deployment.md</a> — most-touched file during bring-up</li>
<li><a href="../docs/11-open-questions/">docs/11-open-questions.md</a> — read <strong>before</strong> assuming defaults</li>
</ul>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
Back to top
</button>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"annotate": null, "base": "../../..", "features": ["navigation.tabs", "navigation.sections", "navigation.expand", "navigation.top", "search.highlight", "search.suggest", "content.code.copy"], "search": "../../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../../../assets/javascripts/bundle.79ae519e.min.js"></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink