Installation

Every GitHub release 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.

Linux (systemd)

The fastest path is the same shape as get.docker.com: it downloads the right archive for your architecture, checks its hash, and installs Ferrum as a systemd service:

curl -fsSL https://raw.githubusercontent.com/anand34577/ferrum/main/scripts/get.sh | sudo sh

To pin a specific version instead of latest:

curl -fsSL https://raw.githubusercontent.com/anand34577/ferrum/main/scripts/get.sh | FERRUM_VERSION=v1.2.3 sudo sh

Or do the same steps by hand from a downloaded archive; this is all scripts/get.sh automates:

tar -xzf ferrum_*_linux_amd64.tar.gz
cd ferrum_*_linux_amd64
sudo ./install.sh

Either way, this creates a dedicated ferrum system user, installs the binary to /usr/local/bin/ferrum, seeds /etc/ferrum/config.yaml, and enables and starts the ferrum.service unit. Data lives in /var/lib/ferrum; logs go through journalctl -u ferrum -f.

To remove it later, grab scripts/linux/uninstall.sh and run it as root, adding -- --purge to also wipe config and data:

curl -fsSL https://raw.githubusercontent.com/anand34577/ferrum/main/scripts/linux/uninstall.sh | sudo bash -s --

Windows (Windows Service)

Expand-Archive ferrum_*_windows_amd64.zip
cd ferrum_*_windows_amd64
.\install-service.ps1   # run as Administrator

This installs the binary to %ProgramFiles%\Ferrum, seeds %ProgramData%\Ferrum\config.yaml, and registers a "Ferrum" Windows service. ferrum.exe 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 %ProgramData%\Ferrum\ferrum.log instead.

Uninstall with .\uninstall-service.ps1, adding -Purge to also remove config and data.

macOS

Download the darwin_amd64 or darwin_arm64 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 launchd.

Docker

Multi-arch images (amd64/arm64) are published to GHCR on every release:

docker run -p 8080:8080 -v ferrum-data:/app/data ghcr.io/anand34577/ferrum:latest

Or build the image locally from source:

docker build -t ferrum .
docker run -p 8080:8080 -v ferrum-data:/app/data ferrum

Mount /app/config as well if you want to supply a config.yaml instead of relying on environment variables; see Configuration.

Building from source

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 ferrum -version reports something meaningful):

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

.\scripts\build.ps1                    # Windows-native equivalent, current platform only

This is exactly what the release workflow runs when a vX.Y.Z tag is pushed: it packages each target as a .tar.gz/.zip with its install script and publishes them, plus a checksums.txt, as GitHub Release assets.

For frontend-only development against a running backend:

cd web
npm install
npm run dev

First run

1. Start Ferrum (whichever way above), then open http://<host>:8080.
2. Create the initial admin account. This screen only ever appears once, against a database with no users yet.
3. Go to Connections and add your first Proxmox connection: host, port, and either an API token or a username/password.

From there, inventory, the fleet dashboard, and alerting all populate on their own within the first polling cycle.