Quickstart

Prerequisites

1 · Build the binary

git clone https://github.com/faratech/httpjet.git
cd httpjet

# release build of just the binary crate (the workspace is large — always scope with -p)
cargo build --release -p httpjet        # → target/release/httpjet

# optional build features (each still needs explicit runtime opt-in):
cargo build --release -p httpjet --features acme,ocsp,otel

A debug build (cargo build -p httpjet) compiles faster but runs ~5× slower — fine for iteration, meaningless for any measurement. For reproducible results use --locked.

2 · Validate a configuration tree

httpjet is configured by a server root containing conf/httpd_config.xml, optional conf/mime.properties, and the per-vhost XML files it references. The checked-in examples/litespeed/ tree is a minimal working example: one plain listener on 127.0.0.1:8080 and one static vhost (example.test) with scripting and symlinks off.

# parse the tree and print a summary (check is also the default subcommand)
target/release/httpjet --root "$PWD/examples/litespeed" check

# strict: lint topology and exit non-zero on findings — the deploy gate
target/release/httpjet --root "$PWD/examples/litespeed" check --strict

check --strict hard-errors on a docroot shared by two vhosts, a vhost whose docroot is missing, and a vhost with no exact vhostMap domain; it warns on an apex mapped without its www. twin, TLS over a Unix socket, PROXY protocol on a public bind, geo rules without a database, ignored LiteSpeed anti-abuse elements, generic CGI contexts, and every other directive that would parse but do nothing. It also prints each vhost's fast-memo verdict (fast_memo: eligible [vary: …]) and a vhost-map-fingerprint for comparing check output over time. Always use an absolute --root.

3 · Serve on loopback

The XML holds persistent policy; serve flags hold operational overrides (addresses, workers, PHP wiring, cache budgets). The example is HTTP-only, PHP-off and cache-off, so it is safe next to an existing server.

target/release/httpjet --root "$PWD/examples/litespeed" serve \
  --http-addr 127.0.0.1:8080 --https-addr "" \
  --workers 1 --no-php

To try TLS and HTTP/3, add a secure listener with keyFile/certFile to the XML, set <quic><quicEnable>1</quicEnable></quic>, and pass --https-addr 127.0.0.1:8443; the same port must be reachable over TCP (h1/h2) and UDP (h3). See TLS, ACME & OCSP.

4 · Verify

printf 'hello from httpjet\n' > examples/litespeed/example/public/index.html
curl -i -H 'Host: example.test' http://127.0.0.1:8080/

# h2c prior knowledge on the same plain port
curl -i --http2-prior-knowledge -H 'Host: example.test' http://127.0.0.1:8080/

# Prometheus metrics (loopback-only by design)
curl -s http://127.0.0.1:9090/metrics | grep -E '^httpjet_(requests_total|active_connections)'

Expect a LiteSpeed-style ETag ("size-mtime-inode;;;"), Vary: Accept-Encoding on compressible bodies, and — once a listener is secure and QUIC is on — an Alt-Svc header advertising h3.

5 · Add PHP (optional)

With an LSAPI-capable lsphp configured in the XML (<phpConfig> or an lsapi extProcessor plus a scriptHandler), drop --no-php and let httpjet spawn its own pool on a private socket. For zero-downtime deploys, run the pool as a separate process instead:

# terminal 1 — the persistent PHP pool
httpjet --root /abs/root lsphp --php-socket /run/httpjet-test/php.sock --php-children 4

# terminal 2 — the web tier dials it and never spawns lsphp itself
httpjet --root /abs/root serve --http-addr 127.0.0.1:8080 --https-addr "" \
  --lsphp-external /run/httpjet-test/php.sock \
  --lsphp-generation-file /run/httpjet-test/php.sock.generation

How the pool, the generation file and lsphp-reload fit together is on LSAPI & PHP.

Where to go next

• Configuration — the XML reference, including the httpjet-native directives.
• CLI reference — every serve flag, grouped and filterable.
• Operations — systemd socket activation, the PHP pool, deploy gates and rollback.
• Page cache — enabling --page-cache safely.
• Migrating from LiteSpeed — the validation-first path for a real tree.