Installation

Installation

Ferrum ships as one statically-linked binary (the web UI is embedded) plus a multi-arch Docker image. Pick whichever fits your setup.

Docker

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

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

Or build locally from source:

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

The container's data volume holds the SQLite database and the encryption secret for stored connection credentials — back it up.

Linux (systemd)

One-liner, same idea as get.docker.com — downloads the latest release for your architecture, verifies its checksum, and installs it as a systemd service:

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

Pin a specific version with FERRUM_VERSION:

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

Or do it by hand from a downloaded release archive — scripts/get.sh just automates these same steps:

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 + starts the ferrum.service systemd unit (packaging/systemd/ferrum.service) — data lives in /var/lib/ferrum, logs go to journalctl -u ferrum -f.

To uninstall, grab scripts/linux/uninstall.sh and run it as root — add -- --purge to also remove config/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, no wrapper (NSSM etc.) needed. Since Windows services don't capture stdout/stderr the way systemd does, logs are written to %ProgramData%\Ferrum\ferrum.log.

Uninstall with .\uninstall-service.ps1 (add -Purge to also remove config/data).

Building from source

go build ./cmd/ferrum
./ferrum -config config.example.yaml

The web UI is served from the same binary (see web/embed.go), so a go build alone gives you an empty/stale UI unless the frontend has been built first:

cd web
npm install
npm run build   # produces web/dist, embedded via go:embed
cd ..
go build ./cmd/ferrum

For frontend development (hot reload against a running backend):

cd web
npm install
npm run dev

Cross-platform packaged builds (the same thing the release workflow produces):

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

Both build the frontend, cross-compile with version info baked in (ferrum -version), and package each target as a .tar.gz/.zip with its install script.

First run

On first run, open the UI and create the initial admin account, then add a Proxmox connection (host, port, and either an API token or username/password) from Connections. Everything past that — notifications, SSO, security policy, AI providers, API/MCP access — is configured from the admin Settings UI, not from environment variables. See Configuration for what's set where.