ferronserver/ferron repository overview

⁠

Ferron - a fast, modern, and easily configurable web server with automatic TLS

⁠Why Ferron?

• High performance - thoroughly optimized for speed with support for high concurrency.
• Memory-safe - built with Rust⁠, which is a programming language that can offer strong memory safety guarantees.
• Automatic TLS - automatic SSL/TLS certificate acquisition and renewal with Let's Encrypt⁠ integration.
• Easy configuration - simple, intuitive configuration with sensible, secure defaults and comprehensive documentation⁠.
• Extensibility - modular architecture for easy customization.
• Powerful reverse proxy - advanced reverse proxy capabilities with support for load balancing and health checks.

⁠Using the Docker image

For more information, read the Ferron documentation⁠.

⁠Installation steps

⁠1. Pull the Ferron Docker image

To download the latest Ferron image from Docker Hub, run the following command:

docker pull ferronserver/ferron:2

⁠2. Run the Ferron container

Once the image is downloaded, start a Ferron container using the command below:

docker run --name myferron -d -p 80:80 --restart=always ferronserver/ferron:2

This command does the following:

• --name myferron - assigns a name (myferron) to the running container.
• -d - runs the container in detached mode (as a background process).
• -p 80:80 - maps port 80 of the container to port 80 on the host machine.
• --restart=always - ensures the container automatically restarts if it stops or if the system reboots.

⁠File structure

Ferron on Docker has following file structure:

• /usr/sbin/ferron - Ferron web server
• /usr/sbin/ferron-passwd - Ferron user password generation tool
• /usr/sbin/ferron-precompress - Ferron static files precompression tool
• /usr/sbin/ferron-yaml2kdl - Ferron configuration conversion tool
• /var/cache/ferron-acme - Ferron’s ACME cache directory (if not explicitly specified in the server configuration)
• /var/log/ferron/access.log - Ferron access log in Combined Log Format (default configuration)
• /var/log/ferron/error.log - Ferron error log (default configuration)
• /var/www/ferron - Ferron’s web root
• /etc/ferron.kdl - Ferron configuration

⁠Using Ferron with Docker Compose

If you’re using Docker Compose, you can define a service for Ferron in your docker-compose.yml file:

services:
  ferron:
    image: ferronserver/ferron:2
    ports:
      - "80:80"
    restart: always

Then, you can start Ferron using:

docker-compose up -d

⁠Example: Ferron with Docker Compose and automatic TLS

If using Ferron with Docker Compose and automatic TLS, you can use the following docker-compose.yml file contents:

services:
  # Ferron container
  ferron:
    image: ferronserver/ferron:2
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./ferron.kdl:/etc/ferron.kdl" # Ferron configuration file
      - "ferron-acme:/var/cache/ferron-acme" # This volume is needed for persistent automatic TLS cache, otherwise the web server will obtain a new certificate on each restart
    restart: always

volumes:
  ferron-acme:

You might also configure Ferron in a “ferron.kdl” file like this:

// Replace "example.com" with your website's domain name
example.com {
    root "/var/www/ferron"
}

Then, you can start Ferron using:

docker-compose up -d

⁠Ferron image tags

Ferron provides the following tags for the Ferron image (for Ferron 2):

• 2 - Based on Distroless, statically-linked binaries
• 2-alpine - Based on Alpine Linux, statically-linked binaries
• 2-debian - Based on Debian GNU/Linux, dynamically-linked binaries (GNU libc required)

⁠Configuration examples

⁠Basic static file serving

// Example configuration with static file serving. Replace "example.com" with your domain name.
example.com {
    root "/var/www/html" // Replace "/var/www/html" with the directory containing your static files
}

⁠Basic reverse proxying

// Example configuration with reverse proxy. Replace "example.com" with your domain name.
example.com {
    proxy "http://localhost:3000/" // Replace "http://localhost:3000" with the backend server URL
}

⁠More examples

You can find more configuration examples for common use cases in the Ferron documentation⁠.

⁠Server configuration

You can check the Ferron documentation⁠ to see configuration properties used by Ferron.

⁠License

Ferron is licensed under the MIT License. See LICENSE in GitHub repository for details.