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