Operating System CentOS

How to Install the H2O Web Server on AlmaLinux 9 or Rocky Linux 9 from Source

Build H2O from its master branch on AlmaLinux 9 or Rocky Linux 9, run it as a systemd service and configure virtual hosts, redirects, TLS and PHP-FPM.

H2O is a fast, MIT-licensed HTTP server with support for HTTP/1.x, HTTP/2 and, experimentally, HTTP/3. This guide builds H2O from source on AlmaLinux 9 or Rocky Linux 9 (CentOS Stream 9 works the same way), runs it as a systemd service, and configures a static site with a www redirect, HTTPS and PHP through PHP-FPM.

Two things have changed since H2O guides were written for CentOS 7, which reached end of life on 30 June 2024. First, the H2O project stopped publishing numbered releases in April 2023; according to its installation documentation, every commit on the master branch is considered stable apart from features marked experimental. Second, the Bintray service that hosted the community RPM repository has shut down, and the unofficial RPM build scripts have not been updated since 2022. Building from source is therefore the route the project documents today, and it is what this guide uses.

Requirements

  • A server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9.
  • A user with sudo rights.
  • A domain name pointing at the server. The examples use example.com and www.example.com.
  • No other web server listening on ports 80 and 443.

Step 1: Install the build dependencies

H2O needs a C/C++ compiler, CMake, pkg-config, the OpenSSL development files and zlib:

sudo dnf upgrade -y
sudo dnf install -y git gcc gcc-c++ make cmake pkgconf-pkg-config openssl-devel zlib-devel

Step 2: Build and install H2O

Clone the repository together with its submodules; the bundled libraries live there and the build fails without them:

cd ~
git clone --recurse-submodules https://github.com/h2o/h2o.git
cd h2o

Configure and compile in a separate build directory:

mkdir -p build
cd build
cmake -DWITH_MRUBY=off ..
make

-DWITH_MRUBY=off leaves out the embedded mruby scripting handler, which keeps the dependency list short. If you want to write request handlers in Ruby, install bison, ruby and ruby-devel first and drop that option; mruby is then enabled automatically.

Install into the default prefix, /usr/local:

sudo make install

Check the binary:

/usr/local/bin/h2o --version

Step 3: Create the user and directories

H2O starts as root to bind ports 80 and 443 and then switches to an unprivileged account. Create that account, the configuration and log directories, and a document root with a test page:

sudo useradd --system --no-create-home --shell /sbin/nologin h2o
sudo mkdir -p /etc/h2o /var/log/h2o /var/www/example.com
echo '<h1>It works</h1>' | sudo tee /var/www/example.com/index.html

Step 4: Write the configuration

H2O is configured with a single YAML file. Indentation matters, so use spaces, not tabs. Create /etc/h2o/h2o.conf:

sudo nano /etc/h2o/h2o.conf

The following configuration serves example.com from the document root and redirects www.example.com to it:

user: h2o
error-log: /var/log/h2o/error.log
access-log: /var/log/h2o/access.log
file.index: [ 'index.html' ]

hosts:
  "example.com:80":
    listen:
      port: 80
    paths:
      "/":
        file.dir: /var/www/example.com
  "www.example.com:80":
    listen:
      port: 80
    paths:
      "/":
        redirect:
          status: 301
          url: "http://example.com/"

To make the www name the canonical one instead, swap the two paths blocks and change the redirect URL. Test the file before you use it:

sudo /usr/local/bin/h2o -t -c /etc/h2o/h2o.conf

Step 5: Run H2O as a systemd service

A source build does not install a service unit, so create one:

sudo nano /etc/systemd/system/h2o.service
[Unit]
Description=H2O HTTP server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStartPre=/usr/local/bin/h2o -t -c /etc/h2o/h2o.conf
ExecStart=/usr/local/bin/h2o -c /etc/h2o/h2o.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target

Without the -m option H2O stays in the foreground, which is what systemd expects from a simple service. Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now h2o
sudo systemctl status h2o

Open the web ports in firewalld:

sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload

Verify from the server, then from a browser:

curl -I http://example.com/
curl -I http://www.example.com/

The first request returns 200, the second a 301 with a location header pointing at http://example.com/.

Step 6: Enable HTTPS

Obtain a certificate for both host names with the ACME client of your choice, then add TLS listeners and turn the plain-HTTP hosts into redirects. With certificate files under /etc/letsencrypt/live/example.com/, the hosts section becomes:

hosts:
  "example.com:443":
    listen:
      port: 443
      ssl:
        certificate-file: /etc/letsencrypt/live/example.com/fullchain.pem
        key-file: /etc/letsencrypt/live/example.com/privkey.pem
        minimum-version: TLSv1.2
    paths:
      "/":
        file.dir: /var/www/example.com
  "www.example.com:443":
    listen:
      port: 443
      ssl:
        certificate-file: /etc/letsencrypt/live/example.com/fullchain.pem
        key-file: /etc/letsencrypt/live/example.com/privkey.pem
        minimum-version: TLSv1.2
    paths:
      "/":
        redirect:
          status: 301
          url: "https://example.com/"
  "example.com:80":
    listen:
      port: 80
    paths:
      "/":
        redirect:
          status: 301
          url: "https://example.com/"
  "www.example.com:80":
    listen:
      port: 80
    paths:
      "/":
        redirect:
          status: 301
          url: "https://example.com/"

Test and restart after every configuration change, and after each certificate renewal so that H2O loads the new files:

sudo /usr/local/bin/h2o -t -c /etc/h2o/h2o.conf
sudo systemctl restart h2o

HTTP/2 needs no extra directive; H2O negotiates it automatically on TLS listeners. Confirm with curl -I --http2 https://example.com/.

Step 7: Serve PHP through PHP-FPM (optional)

H2O does not run PHP itself; it passes requests for .php files to a FastCGI server. Install PHP-FPM:

sudo dnf install -y php-fpm

On the 9 family the default pool listens on the Unix socket /run/php-fpm/www.sock and grants access to the web server accounts named in listen.acl_users. Open /etc/php-fpm.d/www.conf and add the h2o user to that line:

listen.acl_users = apache,nginx,h2o

Start PHP-FPM:

sudo systemctl enable --now php-fpm

Then add a handler for the .php extension at the top level of /etc/h2o/h2o.conf and extend the index list:

file.index: [ 'index.php', 'index.html' ]

file.custom-handler:
  extension: .php
  fastcgi.connect:
    port: /run/php-fpm/www.sock
    type: unix

Restart H2O, place a PHP file in the document root and request it. If you get a 503, check /var/log/h2o/error.log and the socket permissions first.

Updating H2O

Since there are no numbered releases, updating means pulling the current master and rebuilding:

cd ~/h2o
git pull
git submodule update --init --recursive
cd build
cmake -DWITH_MRUBY=off ..
make
sudo make install
sudo systemctl restart h2o

All directives are described in the H2O configuration reference.

Frequently asked questions

Is H2O still maintained?

Yes. The GitHub repository is not archived and receives commits regularly. What ended in April 2023 is the publishing of versioned releases, which is why the binary reports a development version string instead of a release number.

Is there a ready-made package instead of compiling?

The H2O documentation lists a FreeBSD port, a Homebrew formula for macOS, a community Docker image and a community RPM builder. None of them is published by the H2O project itself, and Debian 13 no longer carries an h2o package, so on the RHEL 9 family compiling from source is the dependable option.

How do I rotate the log files?

If the value of access-log or error-log starts with a | character, H2O pipes the log to that command instead of writing a file, so you can hand the stream to a rotation program. Alternatively, rotate the files with logrotate and restart the service afterwards.

Can I enable HTTP/3?

H2O can listen for QUIC by adding a second listen entry with type: quic on UDP port 443, but the project still labels HTTP/3 support experimental. If you try it, also open 443/udp in the firewall.

Share story:

Continue reading other guides on How VPS.