Ferron logo

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

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

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 management tool
  • /var/log/ferron/access.log - Ferron access log in Combined Log Format
  • /var/log/ferron/error.log - Ferron error log
  • /var/www/ferron - Ferron’s web root
  • /etc/ferron.yaml - 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:1
    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:1
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./ferron.yaml:/etc/ferron.yaml" # Ferron configuration file
      - "ferron-acme:/var/cache/acme-cache" # This volume is needed for persistent automatic TLS cache, otherwise the web server will obtain a new certificate on each restart
    restart: always
    depends_on:
      ferron-acme-change-vol-ownership:
        condition: service_completed_successfully

  # Container to change ownership of the volume, necessary for the ACME cache to work properly
  ferron-acme-change-vol-ownership:
    image: alpine
    user: "root"
    volumes:
      - ferron-acme:/tmp/change-ownership
    command: chown nobody:nogroup /tmp/change-ownership

volumes:
  ferron-acme:

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

global:
  secure: true
  enableAutomaticTLS: true
  automaticTLSContactCacheDirectory: "/var/cache/acme-cache"

hosts:
  - domain: "example.com" # Replace "example.com" with your website's domain name
    wwwroot: "/var/www/ferron"

Then, you can start Ferron using:

docker-compose up -d