mirror of
https://github.com/anand34577/ferrum.git
synced 2026-09-20 17:43:21 +00:00
Anand
4ae41a6f1d
- docs/: GitHub Pages site (landing page, docs, live click-through demo) served straight from /docs, no build step. - web-demo/: source for the demo (a copy of web/ with its API layer mocked in-memory) — see web-demo/README.md to rebuild docs/demo after a change. - web/src/lib/auth.tsx: signOut() no longer clears the whole query cache; wiping ["auth","setup-status"] forced it to refetch and re-armed `loading`, stranding the user on a loading/failed screen instead of the Login page. Only non-auth queries are dropped now. - .gitignore: exclude web-demo/node_modules and web-demo/dist (build output, already published as docs/demo). - Drop PRODUCT.md (internal planning brief, not meant for the public repo). - README: link the new docs/demo site.
144 lines
12 KiB
HTML
144 lines
12 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Configuration — Ferrum Docs</title>
|
|
<meta name="description" content="Ferrum's config.yaml and FERRUM_* environment variables: server, database, secret, OIDC, and the built-in local AI provider.">
|
|
<link rel="icon" type="image/svg+xml" href="../assets/favicon.svg">
|
|
<link rel="stylesheet" href="../assets/css/site.css">
|
|
</head>
|
|
<body>
|
|
<header class="topnav">
|
|
<div class="container topnav-row">
|
|
<a href="../index.html" class="brand">
|
|
<span class="brand-mark" aria-label="Ferrum (Fe)"><span class="bm-num">26</span><span class="bm-sym">Fe</span></span>
|
|
Ferrum
|
|
</a>
|
|
<nav class="navlinks">
|
|
<a href="../index.html#features">Product</a>
|
|
<a href="../index.html#look">Screenshots</a>
|
|
<a href="./index.html" aria-current="page">Docs</a>
|
|
<a href="../demo/index.html">Demo</a>
|
|
<a href="https://github.com/anand34577/ferrum/releases" target="_blank" rel="noopener">Releases</a>
|
|
</nav>
|
|
<div class="nav-actions">
|
|
<button class="icon-btn" data-theme-toggle aria-label="Toggle color theme">
|
|
<svg class="i-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M20 14.5A8 8 0 1 1 9.5 4a6.5 6.5 0 0 0 10.5 10.5Z"/></svg>
|
|
<svg class="i-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>
|
|
</button>
|
|
<a class="icon-btn" href="https://github.com/anand34577/ferrum" target="_blank" rel="noopener" aria-label="View source on GitHub">
|
|
<svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 2C6.48 2 2 6.58 2 12.25c0 4.53 2.87 8.37 6.84 9.73.5.1.68-.22.68-.5 0-.24-.01-1.04-.01-1.88-2.78.62-3.37-1.22-3.37-1.22-.46-1.2-1.11-1.52-1.11-1.52-.9-.64.07-.63.07-.63 1 .07 1.53 1.06 1.53 1.06.89 1.57 2.34 1.11 2.91.85.09-.67.35-1.11.63-1.37-2.22-.26-4.56-1.14-4.56-5.07 0-1.12.39-2.03 1.03-2.75-.1-.26-.45-1.31.1-2.72 0 0 .84-.28 2.75 1.05a9.28 9.28 0 0 1 5 0c1.9-1.33 2.74-1.05 2.74-1.05.56 1.41.2 2.46.1 2.72.65.72 1.03 1.63 1.03 2.75 0 3.94-2.35 4.8-4.58 5.06.36.32.68.94.68 1.9 0 1.37-.01 2.48-.01 2.81 0 .28.18.61.69.5A10.03 10.03 0 0 0 22 12.25C22 6.58 17.52 2 12 2Z"/></svg>
|
|
</a>
|
|
<a class="btn btn-primary btn-sm" href="../demo/index.html">Live demo</a>
|
|
<button class="nav-toggle" data-nav-toggle aria-label="Open menu" aria-expanded="false">
|
|
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"><path d="M4 7h16M4 12h16M4 17h16"/></svg>
|
|
</button>
|
|
</div>
|
|
</div>
|
|
</header>
|
|
|
|
<div class="container doc-shell">
|
|
<nav class="doc-nav" aria-label="Documentation">
|
|
<div>
|
|
<h5>Getting started</h5>
|
|
<ul>
|
|
<li><a href="./index.html">Overview</a></li>
|
|
<li><a href="./installation.html">Installation</a></li>
|
|
</ul>
|
|
</div>
|
|
<div>
|
|
<h5>Setup</h5>
|
|
<ul><li><a href="./configuration.html" aria-current="page">Configuration</a></li></ul>
|
|
</div>
|
|
<div>
|
|
<h5>Using Ferrum</h5>
|
|
<ul><li><a href="./features.html">Features & workflows</a></li></ul>
|
|
</div>
|
|
<div>
|
|
<h5>Integrations</h5>
|
|
<ul><li><a href="./api.html">API, MCP & audit log</a></li></ul>
|
|
</div>
|
|
</nav>
|
|
|
|
<article class="doc-content">
|
|
<div class="doc-kicker">Setup</div>
|
|
<h1>Configuration</h1>
|
|
<p>Copy <code>config.example.yaml</code> to <code>config.yaml</code> next to the binary (or at <code>/etc/ferrum/config.yaml</code> on a systemd install) and adjust what you need, or skip the file entirely and set the equivalent <code>FERRUM_*</code> environment variables, which always take precedence over the file.</p>
|
|
|
|
<div class="callout note">
|
|
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="M12 16v-5M12 8h.01"/></svg>
|
|
<p>This file only covers what has to exist before Ferrum can start. Notifications, SSO details beyond the first-boot seed, security policy, system settings, AI providers, and the REST API/MCP switches are all configured from the admin <strong>Settings</strong> UI once Ferrum is running.</p>
|
|
</div>
|
|
|
|
<h2 id="server">Server</h2>
|
|
<table>
|
|
<thead><tr><th>Key</th><th>Env var</th><th>Default</th><th>What it does</th></tr></thead>
|
|
<tbody>
|
|
<tr><td><code>server.addr</code></td><td><code>FERRUM_ADDR</code></td><td><code>:8080</code></td><td>Listen address and port.</td></tr>
|
|
<tr><td><code>server.secureCookies</code></td><td><code>FERRUM_SECURE_COOKIES</code></td><td><code>false</code></td><td>Mark the session cookie <code>Secure</code>. Turn on whenever Ferrum is served over TLS, directly or behind a proxy.</td></tr>
|
|
<tr><td><code>server.behindProxy</code></td><td><code>FERRUM_BEHIND_PROXY</code></td><td><code>false</code></td><td>Read client IPs from <code>X-Forwarded-For</code> and mark the session cookie <code>Secure</code> for requests the proxy reports as HTTPS.</td></tr>
|
|
<tr><td><code>server.tlsCertFile</code> / <code>tlsKeyFile</code></td><td><code>FERRUM_TLS_CERT_FILE</code> / <code>FERRUM_TLS_KEY_FILE</code></td><td><code>""</code></td><td>Set both to have Ferrum terminate TLS itself. Leave blank for plain HTTP behind a reverse proxy, which is the common case.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h2 id="database">Database</h2>
|
|
<table>
|
|
<thead><tr><th>Key</th><th>Env var</th><th>Default</th><th>What it does</th></tr></thead>
|
|
<tbody>
|
|
<tr><td><code>db.driver</code></td><td><code>FERRUM_DB_DRIVER</code></td><td><code>sqlite</code></td><td><code>sqlite</code> or <code>postgres</code>.</td></tr>
|
|
<tr><td><code>db.path</code></td><td><code>FERRUM_DB_PATH</code></td><td><code>./data/ferrum.db</code></td><td>SQLite file path, used when the driver is <code>sqlite</code>.</td></tr>
|
|
<tr><td><code>db.dsn</code></td><td><code>FERRUM_DB_DSN</code></td><td>none</td><td>e.g. <code>postgres://user:pass@localhost:5432/ferrum?sslmode=disable</code>; required when the driver is <code>postgres</code>.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<p>SQLite is the right default for a single-node install. Move to Postgres when you're running more than one Ferrum instance against the same database, or you already have Postgres in your stack and would rather manage backups there.</p>
|
|
|
|
<h2 id="secret">Encryption secret</h2>
|
|
<p><code>secret</code> (<code>FERRUM_SECRET</code>) pins the key used to encrypt stored connection credentials. Leave it blank and Ferrum generates a random one and persists it next to the SQLite file on first run, which is fine for a single-node SQLite install. Set it explicitly, at least 16 characters, whenever multiple instances share one database (Postgres deployments especially), so every instance can decrypt the same stored credentials.</p>
|
|
|
|
<h2 id="oidc">Single sign-on (OIDC)</h2>
|
|
<p>Optional SSO through any standard OpenID Connect provider (Keycloak, Authentik, Entra ID, Okta, and similar). Local username/password login keeps working regardless; this just adds a "Continue with…" button next to it.</p>
|
|
<pre><code>oidc:
|
|
enabled: false # FERRUM_OIDC_ENABLED
|
|
displayName: Keycloak # FERRUM_OIDC_DISPLAY_NAME, shown on the login button
|
|
issuerUrl: https://keycloak.example.com/realms/myrealm
|
|
clientId: ferrum
|
|
clientSecret: "" # from a confidential client in your IdP
|
|
redirectUrl: https://ferrum.example.com/api/v1/auth/oidc/callback</code></pre>
|
|
<p>The first SSO login for a provider-verified email that already has a matching local account links the two automatically; otherwise a new, non-admin account is created. Unverified IdP emails never link into existing accounts, and that first SSO user still needs promoting to admin from the <strong>Users</strong> page.</p>
|
|
<div class="callout warn">
|
|
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M12 9v4M12 17h.01M10.3 3.9 2.5 17a2 2 0 0 0 1.7 3h15.6a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0Z"/></svg>
|
|
<p>This block (and its env equivalents) is a <strong>first-boot seed only</strong>: it's copied into the database once, the first time Ferrum starts against a fresh database. Every boot after that, and any save from <strong>Settings > SSO</strong>, reads and writes the database exclusively; editing the file later has no effect. It exists purely to pre-seed SSO for scripted, first-time deployments.</p>
|
|
</div>
|
|
|
|
<h2 id="needle">Built-in local AI provider (Needle 2)</h2>
|
|
<p>The AI assistant and the MCP tool-calling loop work with any OpenAI-chat-completions-compatible provider (OpenAI, Ollama, LM Studio, LocalAI, OpenRouter) configured from <strong>Settings > AI Providers</strong>. There's also a zero-config option with no API key and no network access at inference time, backed by <a href="https://huggingface.co/Cactus-Compute/needle2" target="_blank" rel="noopener">Needle 2</a>, a 45M-parameter tool-calling model distributed as a self-contained CLI binary.</p>
|
|
<p>On Windows, Linux, and macOS (amd64 or arm64), Ferrum bundles Needle 2's binary directly into itself and registers it automatically as the default assistant the first time it starts with no provider configured: nothing to download, nothing to set. On any other platform there's no bundled binary, and Ferrum never fetches executable content on its own; to use Needle there:</p>
|
|
<ol class="step-list">
|
|
<li>Download the <code>needle</code> CLI binary for your platform from the <a href="https://huggingface.co/Cactus-Compute/needle2/tree/main" target="_blank" rel="noopener">Needle 2 files</a>.</li>
|
|
<li>Point Ferrum at it with <code>needleBinPath</code> in <code>config.yaml</code>, or <code>FERRUM_NEEDLE_BIN=/path/to/needle</code>, which also overrides the bundled binary if you'd rather run a different build.</li>
|
|
</ol>
|
|
<p>Ferrum starts it as a local, <code>127.0.0.1</code>-only subprocess the first time it's used and stops it on shutdown. If nothing is bundled and <code>FERRUM_NEEDLE_BIN</code> isn't set, this provider is simply unavailable; every other provider is unaffected.</p>
|
|
<div class="callout note">
|
|
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="M12 16v-5M12 8h.01"/></svg>
|
|
<p><strong>On small ARM boards</strong> (Raspberry Pi and similar): Needle's one-time tool-retrieval pass over Ferrum's ~60-tool catalog briefly spikes memory and CPU, and on very little RAM the kernel's OOM-killer can take the subprocess out (<code>needle process exited: signal: killed</code>). Set <code>FERRUM_NEEDLE_MAX_TOOLS=<n></code> (e.g. <code>10</code>) to trim the catalog and lighten that pass. If it still fails, the board likely can't run even this small a model reliably; point at a hosted or remote OpenAI-compatible provider instead.</p>
|
|
</div>
|
|
|
|
<div class="doc-footnav">
|
|
<a href="./installation.html"><span class="lbl">Back</span><span class="ttl">← Installation</span></a>
|
|
<a href="./features.html"><span class="lbl">Next</span><span class="ttl">Features & workflows →</span></a>
|
|
</div>
|
|
</article>
|
|
</div>
|
|
|
|
<footer class="site-footer">
|
|
<div class="container footer-bottom" style="margin-top:0; padding-top:0; border-top:none;">
|
|
<span>© 2026 Ferrum. Open source under the MIT license.</span>
|
|
<a href="https://github.com/anand34577/ferrum" target="_blank" rel="noopener">github.com/anand34577/ferrum</a>
|
|
</div>
|
|
</footer>
|
|
|
|
<script src="../assets/js/site.js"></script>
|
|
</body>
|
|
</html>
|