Manual installation from archive - Ferron 3 (RC) documentation

You can install Ferron 3 manually from pre-built binaries in an archive. Archives are available for Windows, macOS, Linux, and FreeBSD.

Prerequisites⁠#

Before installing Ferron, make sure you have:

A supported operating system: Windows 10+, Windows Server 2016+, macOS 12+, or a modern Linux distribution.
Internet connectivity to download the archive.
On Unix-like systems, the unzip or tar utility available in your PATH.

Downloading the archive⁠#

Visit the Ferron downloads page and choose the archive that matches your operating system and architecture:

Windows: .zip archive (for example, ferron-3.0.0-x86_64-pc-windows-msvc.zip)
macOS: .tar.gz archive (for example, ferron-3.0.0-aarch64-apple-darwin.tar.gz)
Linux: .tar.gz archive (for example, ferron-3.0.0-x86_64-unknown-linux-gnu.tar.gz)
FreeBSD: .tar.gz archive (for example, ferron-3.0.0-x86_64-unknown-freebsd.tar.gz)

Note

FIPS-certified archives use a +fips suffix in the archive name. For example, ferron+fips-3.0.0-x86_64-unknown-linux-gnu.tar.gz. A FIPS archive restricts cryptography to FIPS-approved algorithms: OCSP stapling, TLS cipher suites and key exchange groups are filtered, and HTTP basic auth password verification accepts only PBKDF2 hashes (Argon2 and scrypt are rejected). Use a FIPS archive when you must run Ferron in a FIPS-compliant environment.

Every release also publishes a software bill of materials (SBOM) archive. See Software bill of materials.

Installation steps⁠#

1. Extract the archive⁠#

Windows:

Right-click on the downloaded .zip file and select “Extract All…” to extract the contents.
macOS and Linux:

Open a terminal, navigate to the directory containing the downloaded .tar.gz file, and extract it:
```
mkdir ferron
tar -xzf ferron-*.tar.gz -C ferron
```
This creates a directory containing the Ferron binaries and configuration files.

2. Verify the archive (Linux, FreeBSD)⁠#

Run the following command to verify the archive integrity:

# 1. Import the signing key (if not already imported)
wget https://dl.ferron.sh/signing.pgp
gpg --import signing.pgp

# 2. Download the .asc file corresponding to the downloaded .tar.gz archive
# The example below assumes you have downloaded ferron-3.0.0-x86_64-unknown-linux-gnu.tar.gz
#wget https://dl.ferron.sh/3.0.0/ferron-3.0.0-x86_64-unknown-linux-gnu.tar.gz.asc

# 3. Verify the archive's integrity (using the detached signature)
gpg --verify ferron-*.tar.gz.asc

3. Review the extracted contents⁠#

After extraction, you see these files and directories:

ferron or ferron.exe: the main Ferron web server executable.
ferron-fmt or ferron-fmt.exe: a tool for formatting Ferron configuration files.
ferron-kdl2ferron or ferron-kdl2ferron.exe: a tool for converting Ferron 2 KDL configurations to Ferron 3 configurations.
ferron-passwd or ferron-passwd.exe: a tool for generating hashed passwords for the server configuration.
ferron-precompress or ferron-precompress.exe: a tool for precompressing static files.
ferron-serve or ferron-serve.exe: a command for serving static files with Ferron with zero configuration.
ferron.conf: an example configuration file for Ferron.
wwwroot/: the webroot directory containing the default index.html file.

4. Configure Ferron⁠#

Open the ferron.conf file in a text editor. Modify it to suit your server requirements. This file includes settings for server ports, logging, modules, and more. Detailed configuration options are in the server configuration reference.

5. Run Ferron⁠#

Windows:

Open Command Prompt. Navigate to the extracted directory and run:
```
ferron.exe
```
macOS:

Run:
```
./ferron
```
Tip
On macOS, you may need to remove the quarantine attribute first:
```
xattr -d com.apple.quarantine ferron
```
Linux:

Make the binary executable and run it:
```
chmod +x ferron
./ferron
```

6. Access the web server⁠#

By default, Ferron serves content from the wwwroot directory. Open a web browser and navigate to http://localhost to verify the server works.

If you see a “Ferron is installed successfully!” message on the page, the web server works correctly.

Tip

If you cannot access the server from another machine, make sure your firewall allows incoming connections on the configured port (default: 80). If port 80 is in use, change the listen port in ferron.conf. Then update your firewall rules.

Software bill of materials (SBOM)⁠#

Ferron publishes a software bill of materials (SBOM) for every release. An SBOM is a machine-readable inventory of the third-party components in a software product. Ferron builds the SBOM from the Rust crates that are compiled into the binaries.

Download the SBOM archive⁠#

Each SBOM archive has the same base name as the matching binary archive, with a -sbom suffix. The archive format follows the binary archive: .tar.gz for Unix-like systems, .zip for Windows.

Examples:

ferron-3.0.0-x86_64-unknown-linux-gnu-sbom.tar.gz
ferron-3.0.0-x86_64-pc-windows-msvc-sbom.zip
ferron+fips-3.0.0-x86_64-unknown-linux-gnu-sbom.tar.gz

Download SBOM archives from the same place as the binary archives. GitHub releases attach the SBOM archive next to the binary archive.

Contents of the SBOM archive⁠#

Each archive contains one SBOM document per Ferron binary, in two formats:

.cdx.json: CycloneDX in JSON format.
.cdx.xml: CycloneDX in XML format.

Each document lists the third-party Rust crates in the binary, with their versions and package URLs (purl). License information appears when the crate declares it.

Use the SBOM⁠#

You can feed the SBOM to software composition analysis tools, for example Grype, Trivy, or Dependency-Track. The tools match the components against vulnerability databases and license policies. Run this scan before you deploy a release.

Reloading the configuration (Unix)⁠#

To reload the configuration without restarting the server, send a SIGHUP signal to the ferron process:

kill -HUP $(pidof ferron)

Installing as a Windows service⁠#

To install Ferron as a Windows service, use the following command in an elevated PowerShell session (run as administrator):

path\to\ferron winservice install -c path\to\ferron.conf

Replace path\to with the actual path to your Ferron installation directory.

Running as a daemon (Unix)⁠#

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

./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)

Other CLI commands⁠#

Ferron also gives you several commands for working with configuration files:

./ferron validate -c ferron.conf   # validate configuration without starting
./ferron adapt -c ferron.conf      # output configuration as JSON