Quine Webserver Config
quine.webserver-advertise
specifies the canonical address of a Quine instance in the Quine configuration file. Whereas quine.webserver
specifies the address (and therefore the network interface) on which quine listens for traffic, quine.webserver-address
specifies the address Quine uses to reference itself, for example, when constructing self-referential URLs.
Purpose¶
Most enterprise deployments will put Quine behind a reverse proxy, load balancer, or other such network construct. Quine needs to bind to 0.0.0.0 (all interfaces), or a specific network interface, but the end-user reaches quine via a very different address. This may be localhost
, quine.mycompany.com
, or any other URL. Similarly, Quine may be configured to bind to one port, say, 8080
, but be exposed to the user on another port, say 80
. This is particularly common when using a containerized deployment of Quine. Any time Quine generates a self-referential URL (e.g., in the interactive rest API documentation or openAPI schema's servers
block), it should refer to an end-user resolvable address, rather than an interface's address.
Application¶
Consider a simple production deployment of Quine in which the JVM is configured to bind to only the loopback interface on port 8080. That is,
quine.webserver {
# whether the webserver should be enabled
enabled = true
# Hostname or address of the interface to which the HTTP server should
# be bound - 0.0.0.0 means "all interfaces"
# There are two special values which are interpreted dynamically:
# 1.) "<getHostAddress>" uses the host IP found at runtime
# 2.) "<getHostName>" uses the host DNS name found at runtime
address = "127.0.0.1"
# port to which the HTTP server should be bound
# setting to `0` will choose an available port at random.
port = 8080
}
The Quine is then hosted behind a reverse proxy providing TLS termination and exposing the Quine instance at quine.example.com
. The operator wishes to use the interactive rest API documentation. However, by default, the API documentation will render the server URL as //127.0.0.1:8080
, and trying to send API requests via documentation UI will cause errors as the user's browser tries to connect to 127.0.0.1
, which resolves to the user's machine instead of the Quine host. To fix this, the Quine operator can set:
quine.webserver-advertise {
# Hostname or address using which the application should generate
# user-facing hyperlinks to itself. This should be uniquely
# resolvable from the end-users' client.
address = "quine.example.com"
# port (on `address`) via which the HTTP server can be reached
port = 443
}
The documentation will now report the server's URL as //quine.example.com:443
. When the user's browser connects to this URL, their traffic is correctly routed through the TLS termination and reverse proxy to reach their Quine instance.