Install / Linux

Install on Linux

Pre-built binaries for x86_64 and ARM64. No runtime dependencies — a single static binary is all you need.

✅
Current version: v0.9.0 — Download links point to GitHub Releases.
1

Download the Binary

Choose your architecture. Both are statically linked with musl for maximum compatibility.

🐧

Linux x86_64

Intel/AMD 64-bit
🐧

Linux ARM64

AWS Graviton, Raspberry Pi 4+
bash — x86_64
# x86_64
curl -LO https://github.com/ferrum-edge/ferrum-edge/releases/latest/download/ferrum-edge-linux-x86_64

# ARM64 (Graviton, etc.)
# curl -LO https://github.com/ferrum-edge/ferrum-edge/releases/latest/download/ferrum-edge-linux-aarch64
2

Install the Binary

bash
chmod +x ferrum-edge-linux-x86_64
sudo mv ferrum-edge-linux-x86_64 /usr/local/bin/ferrum-edge

# Verify installation
ferrum-edge --version
3

Create a Configuration File

Start with file mode — no database required.

bash
sudo mkdir -p /etc/ferrum
sudo tee /etc/ferrum/config.yaml << 'EOF'
mode: file

admin:
  http_port: 9000
  jwt_secret: "change-me-in-production"

proxies:
  - name: my-api
    listen_port: 8000
    upstream_url: http://localhost:3000
    plugins:
      - name: rate_limiting
        config:
          requests: 1000
          window: minute
          limit_by: ip
      - name: stdout_logging
        config: {}
EOF
4

Start Ferrum Edge

bash
ferrum-edge --config /etc/ferrum/config.yaml

# Verify health
curl http://localhost:9000/health

Systemd Service

For production deployments, run Ferrum Edge as a systemd service with automatic restarts.

1

Create a Dedicated User

bash
sudo useradd --system --no-create-home --shell /bin/false ferrum
2

Create Environment File

bash
sudo tee /etc/ferrum/env << 'EOF'
FERRUM_MODE=database
FERRUM_DATABASE_URL=postgres://ferrum:secret@localhost/ferrum
FERRUM_ADMIN_JWT_SECRET=your-secure-jwt-secret
FERRUM_LOG_LEVEL=info
FERRUM_LOG_FORMAT=json
EOF
sudo chmod 600 /etc/ferrum/env
sudo chown ferrum:ferrum /etc/ferrum/env
3

Create the Systemd Unit File

ini — /etc/systemd/system/ferrum-edge.service
[Unit]
Description=Ferrum Edge API Gateway
Documentation=https://ferrumedge.com
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=ferrum
Group=ferrum
EnvironmentFile=/etc/ferrum/env
ExecStart=/usr/local/bin/ferrum-edge --config /etc/ferrum/config.yaml
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5s
TimeoutStopSec=30s
KillMode=mixed
LimitNOFILE=65536

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/ferrum /var/lib/ferrum

[Install]
WantedBy=multi-user.target
4

Enable and Start the Service

bash
sudo systemctl daemon-reload
sudo systemctl enable ferrum-edge
sudo systemctl start ferrum-edge
sudo systemctl status ferrum-edge

# View logs
sudo journalctl -u ferrum-edge -f

Build from Source

ℹ️
Building from source is required if you want to include custom plugins. Requires Rust 1.85+ and protoc.
bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# Install protoc (Protocol Buffers compiler)
# Ubuntu/Debian:
sudo apt-get install -y protobuf-compiler
# Fedora/RHEL:
# sudo dnf install -y protobuf-compiler

# Clone and build
git clone https://github.com/ferrum-edge/ferrum-edge.git
cd ferrum-edge
cargo build --release

# The binary will be at:
./target/release/ferrum-edge

# Install
sudo cp target/release/ferrum-edge /usr/local/bin/
Admin API Reference → Browse Plugins Docker Install