# GenHTTP Gateway

> A fast, lightweight, self-hosted reverse proxy that serves all your web applications over a single HTTPS entry point, configured in one YAML file. Built for home servers, homelabs, NAS boxes, Raspberry Pis and small VPS hosts. Distributed as the Docker image `genhttp/gateway`, open source under the MIT license.

Compared to reverse proxies such as Traefik, Caddy or nginx, the gateway has fewer features but is easier to configure: no container discovery by labels, no middleware chains, no load balancing and no built-in certificate requests (certbot does that). It is built on the GenHTTP web server for .NET and runs on ioxide, the engine of the fastest HTTP/1.1 web server in the HTTP Arena benchmark.

## Typical uses

- One HTTPS entry point for self-hosted apps such as Nextcloud, Jellyfin, Home Assistant, Immich, Vaultwarden or Gitea
- Admin tools like Portainer and Pi-hole below one domain (`/admin/portainer/`, `/admin/pi-hole/`)
- Several websites or domains on one small VPS
- Sharing a folder from a NAS as a browsable file listing
- Development and staging servers of a small team

## Features

- Virtual hosts: one block per domain; a host named `any` answers everything else
- Nested routes: routes inside routes, e.g. `/admin/portainer/`
- Reverse proxy: `destination:` forwards to any HTTP service on the network
- Static websites: `content:` with `directory:` and an optional `index:`
- Directory listings: `listing:` makes a folder browsable
- Redirects: `location:` sends a path elsewhere
- HTTPS by default: once a host has a certificate, plain HTTP is redirected to HTTPS (301), except ACME challenges
- Let's Encrypt: reads certbot's PEM files directly (`pem:` and `key:`), or a `pfx:` file; serves `.well-known` from the data volume for certbot's webroot mode
- HTTP/1.1, HTTP/2 and HTTP/3 (QUIC) on the secure port, chosen with `protocols:`
- Images for Linux x64, ARM64, ARM32 (Raspberry Pi) and Windows x64

## Speed and resources

The gateway runs on the engines of the GenHTTP web server. Its fastest engine, ioxide (website https://mda2av.github.io/ioxide/, source https://github.com/MDA2AV/ioxide), is built on Linux io_uring and keeps every request on one CPU core from start to finish. GenHTTP on ioxide is the fastest web server on HTTP/1.1 in the independent HTTP Arena benchmark (composite score 7,117, alpha round as of November 2026, 64-core AMD Threadripper), ahead of the best servers written in Rust, Zig, Go and JavaScript; only experimental setups tuned for the benchmark alone score higher. Source: https://www.http-arena.com/leaderboard/

Choose the engine with `engine:` in `gateway.yaml`:

- `ioxide` (fastest, HTTP Arena score 7,117): io_uring, one reactor per CPU core, HTTP/1.1, 2 and 3, Linux x64 with kernel 6.1+ only (image `linux-x64`), experimental; needs the seccomp profile `seccomp-ioxide.json` from the repository because Docker's default profile blocks io_uring
- `kestrel` (default, score 3,090): ASP.NET Core Kestrel, HTTP/1.1, 2 and 3, runs in every image including ARM and Windows
- `internal` (score 4,538): GenHTTP's own engine, HTTP/1.1 only

Against the reverse proxies HTTP Arena measures (its infrastructure ranking), average requests per second on the tests both rankings share. An indirect comparison: every server answers directly, nginx, h2o and Caddy through benchmark modules; no number includes proxying to an app; Traefik, Apache and HAProxy are not in HTTP Arena.

| Test | GenHTTP Gateway (ioxide) | nginx | h2o | Caddy |
|---|---|---|---|---|
| HTTP/1.1 static files over TLS | 730k | 721k | - | 159k |
| HTTP/1.1 plain | 3.41M | 3.28M | 3.64M | 432k |
| HTTP/1.1 short-lived connections | 2.61M | 2.63M | 2.65M | 238k |
| HTTP/1.1 pipelined (16 per batch) | 24.21M | 4.04M | 4.94M | 761k |
| HTTP/1.1 JSON over TLS | 1.03M | 1.31M | 1.23M | 322k |
| HTTP/2 plain | 9.37M | 3.37M | 15.87M | 389k |
| HTTP/2 static files | 552k | 799k | 353k | 115k |
| HTTP/3 plain | 1.94M | 4.85M | - | 361k |
| HTTP/3 static files | 237k | 361k | - | 22k |

ioxide is level with nginx and h2o on plain HTTP/1.1, short-lived connections and static files over TLS, several times faster on pipelined HTTP/1.1, faster than nginx on plain HTTP/2, behind nginx on JSON over TLS, static files over HTTP/2 and HTTP/3, and 3 to 32 times faster than Caddy in every test.

Efficient CPU usage, from HTTP Arena's fixed-rate tests:

- Latency-10K: a steady 10,000 requests per second costs ioxide a quarter of one CPU core (24.9%), at 75 microseconds mean latency; it does not busy-poll
- 8Gbit: echoing 10 KB bodies over TLS 50,000 times a second (about 8 Gbit/s) takes 2.7 CPU cores
- Latency-1M: 0.1 ms (103.5 microseconds) mean latency at a million requests per second

## Setup

```bash
docker run -d -p 80:80 -p 443:443 \
  -v /data/gateway/config:/app/config \
  -v /data/gateway/data:/app/data \
  -v /etc/letsencrypt:/app/certs:ro \
  --name gateway \
  genhttp/gateway
```

On first start, an example `gateway.yaml` is written to the config volume. Edit it and restart the container.

```yaml
engine: kestrel
ports:
  plain: 80
  secure: 443
protocols:
  - http1
  - http2
hosts:
  domain1.com:
    default:
      destination: http://10.0.0.2:8080
    routes:
      admin:
        routes:
          portainer:
            destination: http://10.0.0.2:9000
          pi-hole:
            destination: http://10.0.0.3/admin/
      files:
        listing: /data/files/
      site:
        content:
          directory: /data/content/
          index: index.html
    security:
      certificate:
        pem: live/domain1.com/fullchain.pem
        key: live/domain1.com/privkey.pem
```

Certificates with certbot, while the gateway runs:

```bash
certbot certonly --webroot -w /data/gateway/data/ -d domain1.com
certbot renew --deploy-hook "docker restart gateway"
```

Mount all of `/etc/letsencrypt` (the files in `live/` link into `archive/`). For HTTP/3, add `http3` to `protocols` and publish `-p 443:443/udp`.

Image tags: `latest` (multi-arch), `linux-x64` (the only one with ioxide), `linux-arm64`, `linux-arm32`, `windows-x64`.

## Links

- Docker Hub: https://hub.docker.com/r/genhttp/gateway
- Source: https://github.com/Kaliumhexacyanoferrat/GenHTTP.Gateway
- Discord: https://discord.gg/PRkwKrnrB4
- GenHTTP web server: https://genhttp.org/
- ioxide engine: https://mda2av.github.io/ioxide/ (source: https://github.com/MDA2AV/ioxide)
- HTTP Arena benchmark: https://www.http-arena.com