Installation via Docker

Prerequisites

Before proceeding with the installation, ensure you have the following:

A system with Docker installed. If Docker is not installed, follow the official Docker installation guide.
Internet connectivity to pull the Ferron Docker image.

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 following command:

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

Verifying the installation

To confirm that Ferron is running, execute:

docker ps

This should display a running container with the name myferron.

To test the web server, open a browser and navigate to http://localhost. You should see the default Ferron welcome page.

Alternatively, use curl:

curl http://localhost

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-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

Managing the Ferron container

Stopping the container

To stop the Ferron container, run:

docker stop myferron

Restarting the container

To restart the container:

docker start myferron

Removing the container

If you need to remove the Ferron container:

docker rm -f myferron

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.x):

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)