mirror of
https://github.com/anand34577/ferrum.git
synced 2026-09-21 01:53:19 +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.
142 lines
9.8 KiB
HTML
142 lines
9.8 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Installation — Ferrum Docs</title>
|
|
<meta name="description" content="Build Ferrum from source or install a release build on Linux (systemd), Windows (service), macOS, or Docker.">
|
|
<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" aria-current="page">Installation</a></li>
|
|
</ul>
|
|
</div>
|
|
<div>
|
|
<h5>Setup</h5>
|
|
<ul><li><a href="./configuration.html">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">Getting started</div>
|
|
<h1>Installation</h1>
|
|
<p>Every <a href="https://github.com/anand34577/ferrum/releases" target="_blank" rel="noopener">GitHub release</a> ships prebuilt, statically-linked archives for Linux, Windows, and macOS (amd64 and arm64 each), with nothing else to install on the target machine: no Go toolchain, no CGO. Pick the section below for what you're deploying to, or build it yourself from source.</p>
|
|
|
|
<h2 id="linux">Linux (systemd)</h2>
|
|
<p>The fastest path is the same shape as <code>get.docker.com</code>: it downloads the right archive for your architecture, checks its hash, and installs Ferrum as a systemd service:</p>
|
|
<pre><code>curl -fsSL https://raw.githubusercontent.com/anand34577/ferrum/main/scripts/get.sh | sudo sh</code></pre>
|
|
<p>To pin a specific version instead of latest:</p>
|
|
<pre><code>curl -fsSL https://raw.githubusercontent.com/anand34577/ferrum/main/scripts/get.sh | FERRUM_VERSION=v1.2.3 sudo sh</code></pre>
|
|
<p>Or do the same steps by hand from a downloaded archive; this is all <code>scripts/get.sh</code> automates:</p>
|
|
<pre><code>tar -xzf ferrum_*_linux_amd64.tar.gz
|
|
cd ferrum_*_linux_amd64
|
|
sudo ./install.sh</code></pre>
|
|
<p>Either way, this creates a dedicated <code>ferrum</code> system user, installs the binary to <code>/usr/local/bin/ferrum</code>, seeds <code>/etc/ferrum/config.yaml</code>, and enables and starts the <code>ferrum.service</code> unit. Data lives in <code>/var/lib/ferrum</code>; logs go through <code>journalctl -u ferrum -f</code>.</p>
|
|
<p>To remove it later, grab <code>scripts/linux/uninstall.sh</code> and run it as root, adding <code>-- --purge</code> to also wipe config and data:</p>
|
|
<pre><code>curl -fsSL https://raw.githubusercontent.com/anand34577/ferrum/main/scripts/linux/uninstall.sh | sudo bash -s --</code></pre>
|
|
|
|
<h2 id="windows">Windows (Windows Service)</h2>
|
|
<pre><code>Expand-Archive ferrum_*_windows_amd64.zip
|
|
cd ferrum_*_windows_amd64
|
|
.\install-service.ps1 # run as Administrator</code></pre>
|
|
<p>This installs the binary to <code>%ProgramFiles%\Ferrum</code>, seeds <code>%ProgramData%\Ferrum\config.yaml</code>, and registers a "Ferrum" Windows service. <code>ferrum.exe</code> detects it's running under the Service Control Manager and manages its own start/stop lifecycle, so no NSSM or other wrapper is needed. Since Windows services don't capture stdout the way systemd does, logs are written to <code>%ProgramData%\Ferrum\ferrum.log</code> instead.</p>
|
|
<p>Uninstall with <code>.\uninstall-service.ps1</code>, adding <code>-Purge</code> to also remove config and data.</p>
|
|
|
|
<h2 id="macos">macOS</h2>
|
|
<p>Download the <code>darwin_amd64</code> or <code>darwin_arm64</code> archive from the releases page, extract it, and run the binary directly, or use the bundled install script the same way as the Linux archive if you want it running as a background service via <code>launchd</code>.</p>
|
|
|
|
<h2 id="docker">Docker</h2>
|
|
<p>Multi-arch images (amd64/arm64) are published to GHCR on every release:</p>
|
|
<pre><code>docker run -p 8080:8080 -v ferrum-data:/app/data ghcr.io/anand34577/ferrum:latest</code></pre>
|
|
<p>Or build the image locally from source:</p>
|
|
<pre><code>docker build -t ferrum .
|
|
docker run -p 8080:8080 -v ferrum-data:/app/data ferrum</code></pre>
|
|
<p>Mount <code>/app/config</code> as well if you want to supply a <code>config.yaml</code> instead of relying on environment variables; see <a href="./configuration.html">Configuration</a>.</p>
|
|
|
|
<h2 id="source">Building from source</h2>
|
|
<p>You'll need Go and Node installed. The build scripts compile the frontend, embed it into the binary, and cross-compile with version info baked in (so <code>ferrum -version</code> reports something meaningful):</p>
|
|
<pre><code>scripts/build.sh # current platform only, output in dist/
|
|
scripts/build.sh linux/amd64 windows/amd64
|
|
scripts/build.sh all # every platform the release workflow builds</code></pre>
|
|
<pre><code>.\scripts\build.ps1 # Windows-native equivalent, current platform only</code></pre>
|
|
<p>This is exactly what the release workflow runs when a <code>vX.Y.Z</code> tag is pushed: it packages each target as a <code>.tar.gz</code>/<code>.zip</code> with its install script and publishes them, plus a <code>checksums.txt</code>, as GitHub Release assets.</p>
|
|
<p>For frontend-only development against a running backend:</p>
|
|
<pre><code>cd web
|
|
npm install
|
|
npm run dev</code></pre>
|
|
|
|
<h2 id="first-run">First run</h2>
|
|
<ol class="step-list">
|
|
<li>Start Ferrum (whichever way above), then open <code>http://<host>:8080</code>.</li>
|
|
<li>Create the initial admin account. This screen only ever appears once, against a database with no users yet.</li>
|
|
<li>Go to <strong>Connections</strong> and add your first Proxmox connection: host, port, and either an API token or a username/password.</li>
|
|
</ol>
|
|
<p>From there, inventory, the fleet dashboard, and alerting all populate on their own within the first polling cycle.</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>Ferrum defaults to plain HTTP. If it's reachable from anywhere other than your own machine, put a TLS-terminating reverse proxy in front of it (or set <code>tlsCertFile</code>/<code>tlsKeyFile</code> to have it terminate TLS itself) and enable <code>secureCookies</code>; see <a href="./configuration.html#server">Configuration</a>.</p>
|
|
</div>
|
|
|
|
<div class="doc-footnav">
|
|
<a href="./index.html"><span class="lbl">Back</span><span class="ttl">← Overview</span></a>
|
|
<a href="./configuration.html"><span class="lbl">Next</span><span class="ttl">Configuration →</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>
|