Installation
Install Ferrum Edge
Multiple installation options to fit your infrastructure. From a single binary download to a Kubernetes Helm deployment.
Choose Your Path
Installation Options
🐧
Linux
Pre-built binary for x86_64 and ARM64. Systemd service included.
Recommended
macOS
Intel and Apple Silicon (ARM64) binaries. Native performance on M-series chips.
Apple Silicon Ready🐳
Docker
Container-first deployment. Compose files for all operating modes.
Container Ready⎈
Kubernetes
Production K8s deployment with HPA, health probes, and CP/DP mode support.
Production Ready⚙
From Source
Build with custom plugins. Requires Rust 1.85+ and protoc.
bash
cargo build --release
Configuration
Key Environment Variables
The most commonly used environment variables. Over 300 are available — see docs/configuration.md for the complete list.
| Variable | Description | Default | Example |
|---|---|---|---|
FERRUM_MODE | Operating mode (required) | — | file | database | cp | dp | mesh | injector | node_agent | migrate |
FERRUM_FILE_CONFIG_PATH | Path to YAML/JSON config file (file mode) | — | /etc/ferrum/config.yaml |
FERRUM_DB_TYPE | Database backend (db/cp modes) | — | postgres | mysql | sqlite | mongodb |
FERRUM_DB_URL | Database connection string | — | postgres://user:pass@localhost/ferrum |
FERRUM_PROXY_HTTP_PORT | HTTP proxy port (0 = disabled) | 8000 | 8000 |
FERRUM_PROXY_HTTPS_PORT | HTTPS proxy port | 8443 | 8443 |
FERRUM_ADMIN_HTTP_PORT | Admin API HTTP port (0 = disabled) | 9000 | 9000 |
FERRUM_ADMIN_JWT_SECRET | HS256 secret for Admin API auth (min 32 chars, db/cp modes) | — | a-32-plus-character-secret... |
FERRUM_ADMIN_BIND_ADDRESS | Admin API bind address | — | 127.0.0.1 |
FERRUM_CP_GRPC_LISTEN_ADDR | gRPC listen address (CP mode) | — | 0.0.0.0:50051 |
FERRUM_DP_CP_GRPC_URLS | Control Plane URL list (DP mode, failover order) | — | https://cp1:50051,https://cp2:50051 |
FERRUM_CP_DP_GRPC_JWT_SECRET | Shared secret for CP↔DP sync (min 32 chars) | — | a-32-plus-character-secret... |
FERRUM_LOG_LEVEL | Log verbosity | warn | error | warn | info | debug | trace |
Quick Reference
Operating Modes at a Glance
| Mode | Config Source | Admin API | Use Case | Ports |
|---|---|---|---|---|
| file | YAML file on disk | Read-only | Dev, single-node, GitOps | 8000, 8443, 9000 |
| database | PostgreSQL / MySQL / SQLite / MongoDB | Full CRUD | Standard production | 8000, 8443, 9000, 9443 |
| cp | Database → distributes via gRPC | Full CRUD | Distributed / multi-region control plane | 9000, 9443, 50051 |
| dp | Control Plane gRPC stream | Read-only | Stateless request workers | 8000, 8443 |
| mesh | MeshSubscribe, xDS ADS, or local file | Read-only | Service mesh data plane (six topologies) | 8000, 8443 |
| injector | Kubernetes admission webhook | — | Auto-inject mesh sidecars into pods | webhook TLS port |
| node_agent | Kubernetes node state | Optional (read-only) | Per-node eBPF capture for ambient mesh | — |
| migrate | Database | — | Run DB schema migrations, then exit | — |
Port reference: 8000 (HTTP proxy), 8443 (HTTPS proxy), 9000 (Admin HTTP),
9443 (Admin HTTPS), 50051 (Control Plane gRPC). All ports are configurable.