xTQ Web documentation

xTQ Web (xtq-web) is a web server and reverse proxy in one static binary. It answers HTTP and HTTPS, picks a site by hostname, picks a route by path, and then proxies to your apps, serves files from disk, redirects, or answers with a fixed response.

What it does:

Reverse proxy to any HTTP backend over TCP or a Unix socket, with load balancing, active and passive health checks, WebSockets and streamed responses.
Static files with byte ranges, a memory cache for small files and on-the-fly compression.
HTTPS with certificates from Let's Encrypt, issued and renewed on its own.
Protection under load: a cap on requests in flight per backend pool, an optional browser check, caps on connections and TLS handshakes, and a short answer for scanner probes.
Reloads without dropping anyone. A config with a mistake in it is refused and the running one keeps serving.
A live dashboard and Prometheus metrics behind a token.

It also fronts xTQ PHP with a page cache and a waiting room, see Handlers.

xTQ Web is free for personal and non-commercial use. Commercial use needs a license from xTQ, Milian E. (zEmi_69). The LICENSE file in every download has the terms.

Quick start

This takes about five minutes on a Linux server with systemd. You need root or sudo.

Install

curl -fsSL https://xtq.ro/web/install.sh | sh

The installer downloads the latest release, checks its SHA-256 sum, puts the binary in /usr/local/bin/xtq-web, writes /etc/xtq-web/xtq-web.conf from the example (only if you don't have one yet), creates the xtq-web system user and starts the xtq-web systemd service. Install has the details, the Docker variant and the manual way.

Write a minimal config

Say your app listens on 127.0.0.1:3000 and should answer for example.com. Replace the contents of /etc/xtq-web/xtq-web.conf with:

bind 0.0.0.0:80

site example.com www.example.com {
    proxy 127.0.0.1:3000
}

site * {
    respond 404 "unknown site"
}

bind says where sites listen. A site block lists hostnames and says how to answer them. site * catches every other hostname.

Check it

xtq-web check /etc/xtq-web/xtq-web.conf

A good config prints a summary and exits with status 0:

/etc/xtq-web/xtq-web.conf: OK
  listeners: 0.0.0.0:80
  sites:     example.com, *
  proxies:   1 routes, 1 backends
  php:       0

A bad one prints the file, the line and what is wrong, and exits with a non-zero status. Nothing running is touched.

Start it

The installer already started the service. If you installed by hand:

sudo systemctl enable --now xtq-web

Without systemd, run it in the foreground. Logs go to standard error.

sudo XTQW_CONFIG=/etc/xtq-web/xtq-web.conf xtq-web

Try it from the server itself:

curl -i -H 'Host: example.com' http://127.0.0.1/

Reload after a change

sudo systemctl reload xtq-web

The service runs xtq-web check first and sends SIGHUP only if the config is valid. New requests use the new config right away. Requests already in flight finish on the old one. If you send SIGHUP yourself and the config is broken, the process logs reload refused, still serving the previous config and carries on.

Turn on HTTPS

Point the DNS of your hostnames at the server, make sure port 80 is reachable from the internet, add a TLS listener and set XTQW_ACME=1:

bind 0.0.0.0:80
https 0.0.0.0:443

sudo systemctl edit xtq-web

[Service]
Environment=XTQW_ACME=1

sudo systemctl restart xtq-web

Certificates for every exact hostname in your sites are issued from Let's Encrypt and renewed on their own. HTTPS explains the requirements.