Docs

Getting started with Ferron

If this is your first time using a web server, start here.

Ferron can do two common jobs:

  • Serve files directly (HTML/CSS/JS/images) from disk.
  • Forward requests to an app server (reverse proxying).

You can also combine both in one config.

Web server basics in 60 seconds⁠#

A web server listens for HTTP/HTTPS requests and returns responses.

  • Static file serving - the server reads files from disk and sends them to the client.
  • Reverse proxying - the server forwards requests to another server (for example Node.js, Python, Go, Java, or another API service), then returns that response to the client.

Which setup should you choose?⁠#

Choose static file serving if:

  • You have a static website, docs site, landing page, or built frontend files.
  • You do not need app logic on each request.
  • Your content mostly comes from files in a directory.

Choose reverse proxying if:

  • You run an app process that generates responses dynamically.
  • You already have a backend listening on a port/socket.
  • You need Ferron in front for TLS, routing, caching, or observability.

Choose a mixed setup if:

  • You serve frontend files and proxy API/app requests (for example /api).

First configuration examples⁠#

1. Static file serving⁠#

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

2. Reverse proxying⁠#

// Replace "example.com" with your domain name
example.com {
    proxy "http://localhost:3000/" // Replace with your backend URL
}

3. Mixed setup (static site + API)⁠#

// Replace "example.com" with your domain name
example.com {
    location "/api" remove_base=#true {
        proxy "http://localhost:3000/api"
    }

    location "/" {
        root "/var/www/html"
    }
}
  1. Install Ferron using one of these guides:
  2. Pick one setup from this page.
  3. Use a related use-case guide, such as Static file serving, Reverse proxying, or Web applications.
  4. Start with a minimal config first, then add TLS/security/routing features.

Common beginner mistakes⁠#

  • Using root when you actually need proxy to a running app process.
  • Proxying everything to an app when your content is only static files.
  • Mixing static and API traffic without route separation (for example, missing location "/api").
  • Copying a complex configuration before verifying a minimal working setup.

Next reads⁠#