Building Ferron 3 from source (default modules)

This page describes how to build Ferron 3 from source, with default modules.

Prerequisites

Before building Ferron, make sure you have the following installed:

• Rust toolchain — Ferron is written in Rust and requires cargo to build. You can install Rust from rustup.rs.
• Git — needed to clone the repository.

Building from source

Clone the Ferron repository and check out the latest development branch:

git clone https://github.com/ferronweb/ferron -b 3.x
cd ferron

Build the entire workspace:

cargo build -r --workspace

This compiles all crates in the workspace, including the ferron binary and all module crates.

Running the server

Once the build completes, you can run Ferron directly with cargo run:

cargo run -r -p ferron -- run -c ferron.conf

To enable debug-level logging, add the --verbose flag:

cargo run -r -p ferron -- run -c ferron.conf --verbose

Other CLI commands

Ferron provides several commands for working with configuration files:

cargo run -r -p ferron -- validate -c ferron.conf   # validate configuration without starting
cargo run -r -p ferron -- adapt -c ferron.conf      # output configuration as JSON

Running as a daemon (Unix)

On Unix systems, you can run Ferron as a background daemon with a PID file:

cargo run -r -p ferron -- daemon -c ferron.conf --pid-file /var/run/ferron.pid

You can then reload the daemon using its PID file:

kill -HUP $(cat /var/run/ferron.pid)

Running tests and checks

Before submitting changes or if you suspect issues, run the full test suite and code checks:

cargo test --workspace                              # run all workspace tests
cargo fmt --all --check                             # verify code formatting
cargo clippy --workspace --all-targets -- -D warnings  # run linter with warnings as errors

Notes and troubleshooting

• Build times — the first build will take longer as Cargo downloads and compiles all dependencies. Subsequent builds are faster.