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.