|
Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
|
Deploying Orbit applications to production is straightforward thanks to its minimal runtime footprint. The recommended approach is to use Docker to containerize the compiled binary along with its dynamic library dependencies.
Orbit provides a multi-stage Dockerfile in the root repository.
The build works in two stages:
libpq-dev, libmariadb-dev, etc.). It also fetches and compiles quictls, ngtcp2, and nghttp3 for HTTP/3 support..so files) into a clean, lightweight Ubuntu image.When running the container, remember to expose the necessary TCP and UDP ports (UDP is strictly required if you have HTTP/3 enabled).
For complex applications that require databases (PostgreSQL, Redis), docker-compose is the most robust way to manage the stack.
Review the docker-compose.yml included in the root directory:
Simply run:
| Field | CLI | Default | Meaning |
|---|---|---|---|
host | -b, --bind | 0.0.0.0 | Address to listen on. 0.0.0.0 = all IPv4 interfaces, :: = all IPv6 and IPv4 (dual-stack), 127.0.0.1 / ::1 = local only. Host names such as localhost are resolved. |
backlog | --backlog | 0 (SOMAXCONN) | Length of the kernel's pending-connection queue. |
max_connections | --max-connections | 0 (unlimited) | Connections served at once. When reached, the server stops accepting; new connections wait in the backlog until a slot frees up. |
Behind a reverse proxy on the same host, bind to 127.0.0.1 so the app port is not reachable from outside:
On a dual-stack listener, IPv4 clients appear in req.client_ip as plain addresses (203.0.113.7), not as ::ffff:203.0.113.7.
| Field | Default | Applies to |
|---|---|---|
max_body_size | 10 MiB | Request body (413 when exceeded) |
max_header_bytes | 8192 | Request line plus all headers (431) |
max_request_line | 4096 | Method, target and version (431) |
max_headers | 100 | Header fields per request (431) |
websocket_max_message_size | 16 MiB | One WebSocket message after decompression (closes with 1009) |
websocket_ping_interval makes the server ping every WebSocket connection. Live clients answer with a pong, which counts as traffic; combined with websocket_idle_timeout (set it to two or three ping intervals), dead peers are dropped and healthy ones are kept. Only traffic from the client resets the idle timer.
On SIGTERM or SIGINT (or app.shutdown()), the server drains instead of dropping connections:
Connection: close. HTTP/2 clients get GOAWAY; WebSocket clients get close code 1001 (going away).shutdown_timeout (default 30 s) is closed, and listen() returns.A second signal stops immediately. app.stop() also stops immediately.
/healthz answers 200 while the process runs. /readyz answers 200 while serving and 503 once draining has begun. In Kubernetes:
ServerConfig has one timeout per phase of a connection. A value of 0 disables that timeout.
| Field | Default | Applies to |
|---|---|---|
header_timeout | 10 s | From the first byte of a request until its headers are complete. Later bytes do not extend it, so a client cannot hold a connection by trickling header bytes. |
keep_alive_timeout | 10 s | Idle time between requests on a persistent connection. |
idle_timeout | 30 s | Longest pause while receiving a request body or writing a response. |
websocket_idle_timeout | 0 (off) | Idle time on WebSocket and raw-stream connections. |
No timeout runs while a handler is executing, so slow handlers and Server-Sent Events streams are not cut off. WebSocket connections stay open while quiet; to drop dead peers, set websocket_idle_timeout and have clients send pings.
ssl_cert / ssl_key (-c / -k) set the default certificate. More certificates can be served from the same port, chosen by the name the client asks for (SNI):
On the command line: --sni-cert <cert> <key>, repeatable. Each certificate answers for the DNS names in its subjectAltName (or its CN if it has none), including wildcards such as *.example.org (one label). An exact name wins over a wildcard; clients asking for any other name, or sending no SNI, get the default certificate.
Renewing without a restart. The certificate and key files are re-read, and new handshakes use them while open connections continue, when:
SIGHUP (POSIX), e.g. from a certbot deploy hook: systemctl kill -s HUP orbit;tls_reload_interval (--tls-reload-interval <seconds>) is set and a file's size or modification time changed, which suits Kubernetes secrets and cert-manager;app.reload_tls().If any file cannot be loaded, or a key does not match its certificate, the reload is refused, the error is logged, and the current certificates stay in use.
While Orbit is perfectly capable of being exposed directly to the public internet (and features its own Load Balancing and Proxy middlewares), you may wish to run it behind an enterprise reverse proxy like NGINX.
Warning: NGINX does not natively proxy HTTP/3 (QUIC) to backend servers. If you put Orbit behind NGINX, you will lose end-to-end QUIC termination unless configured explicitly using NGINX's experimental QUIC routing.
If using NGINX, ensure you configure it to pass standard HTTP headers to Orbit:
Behind a proxy that terminates TLS, Orbit can also speak HTTP/2 over the plaintext hop. With HTTP/2 enabled (--http-version 2, or 3), a plaintext connection that opens with the HTTP/2 connection preface is served as HTTP/2 ("prior knowledge", RFC 9113 section 3.3); other connections on the same port keep using HTTP/1.1. The Upgrade: h2c handshake is not supported, as RFC 9113 deprecated it. For example, Envoy (http2_protocol_options on the upstream cluster), HAProxy (proto h2 on the server line) and curl --http2-prior-knowledge all use prior knowledge.
To deploy without Docker on a Linux VPS (Ubuntu/Debian):
basic_server) to /usr/local/bin/orbit-server.Create a systemd service file /etc/systemd/system/orbit.service: