Skip to content

Reverse Proxy

A reverse proxy gives a product one address for its web UI, REST API and websockets. On a cluster, that address spreads requests across the members that were ready at the last up, so the whole cluster is one URL instead of a list of ports. Hot spares get no requests; when a spare takes over from a failed member, run quinectl up to add it to the proxy.

With services.proxy: nginx, quinectl runs an nginx container in front of one product:

quinectl.yaml
quine:
  edition: enterprise
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
services:
  persistor: cassandra
  auth: keycloak
  proxy: nginx
  metrics: none
  kafka: none

The proxy listens on http://localhost, port 80. The product's own port keeps working too, but with Keycloak auth, signing in returns you to the proxy's address. The proxy works with or without auth.

Port and HTTPS

To choose the port, or serve HTTPS, use the long form:

quinectl.yaml
quine:
  edition: enterprise
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
services:
  persistor: cassandra
  auth: keycloak
  proxy:
    nginx:
      port: 18000
      tls: true
  metrics: none
  kafka: none
  • tls: true serves HTTPS at the proxy, on port 443 unless you set port. The certificate comes from the same local certificate authority as Keycloak's, so once you trust that authority your browser accepts it. See Trusting the local certificate.
  • With a publicUrl, the proxy answers on that host. Its scheme and port must match the proxy's, so https with tls: true, or up refuses the file.
  • target chooses which product the proxy fronts when both run: quine or novelty. It defaults to quine, wherever the blocks sit in the file. One proxy fronts one product.

With tls: true, the port serves HTTPS only. A plain http:// request to it gets 400 Bad Request, with no redirect to HTTPS.

After launching, up sends a request through the proxy to check it reaches the product, and fails if it doesn't. For the long form above, the line looks like this:

✓ proxy converged: https://localhost:18000

The generated nginx configuration is in conf/proxy.conf in your project directory.

Both products and several projects

With Keycloak auth on for both products, the product behind the proxy is served on localhost and the other on 127.0.0.1; see Two products, two addresses.

Each project that turns the proxy on gets its own nginx container, so give each a different port.

Changing or turning off the proxy

The proxy changes the address the product behind it advertises, so turning it on or off, or changing its port, tls or target, restarts that product on the next up.

Turning the proxy off leaves nginx running

With proxy: none, the next up doesn't stop the proxy's container. nginx keeps answering on its port, and quinectl status no longer shows it. To remove it, run quinectl down, then quinectl down --rm. The proxy is this project's own, so down --rm removes it even when other projects keep the shared services running. When no other project uses them, down --rm also removes the shared service containers, including Cassandra and the graph in it; see Stopping and removing.

Next steps