Skip to content

Local Hostnames

With publicUrl, each service gets a name of its own on your machine, such as quine.localhost, in place of localhost and a port. Names help in two cases:

  • Both products at once. Without names, one product is on localhost and the other on 127.0.0.1, so that you can stay signed in to both; see Two products, two addresses. With names, each has an address of its own instead.
  • A secure connection error at localhost after you trusted quinectl's certificate; see below.

Choosing a name

Pick a name that your browser and tools can resolve to your machine:

Name Setup Notes
quine.localhost None in Chrome or Chromium Other browsers and tools may not resolve it. Add it to /etc/hosts for those
quine.test An /etc/hosts line Works after a secure connection error at localhost
A name ending .local Avoid it On macOS these resolve slowly or not at all

If up can't resolve a name, such as a name you haven't added to /etc/hosts yet, it warns and carries on:

warning: quine.publicUrl host quine2.demo.example.com does not resolve here — add it to /etc/hosts or use a name that does

Quine Enterprise

Set a publicUrl on the product and on Keycloak:

quinectl.yaml
quine:
  edition: enterprise
  publicUrl: http://quine.localhost:8080
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
services:
  persistor: cassandra
  auth:
    keycloak:
      publicUrl: https://keycloak.localhost:8443
  proxy: none
  metrics: none
  kafka: none

Run quinectl up, then open http://quine.localhost:8080. up reports the new address:

warning: services.auth.keycloak.publicUrl is https but secureCookies is false -- session cookies will be sent without the Secure attribute
✓ quine is up: http://quine.localhost:8080

You can ignore that warning here. Leave secureCookies off, because Quine Enterprise itself is on plain HTTP.

Name Keycloak as well as the product. If only the product has a name, sign-in can still fail with a secure connection error.

Both products and Grafana

Give each one its own name. Sign-in to Quine Enterprise and Novelty then lasts side by side:

quinectl.yaml
quine:
  edition: enterprise
  publicUrl: http://quine.localhost:8080
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
novelty:
  port: 8090
  publicUrl: http://novelty.localhost:8090
  licenseKey: ${NOVELTY_LICENSE_KEY}
  customerId: ${NOVELTY_CUSTOMER_ID}
services:
  persistor: cassandra
  auth:
    keycloak:
      publicUrl: https://keycloak.localhost:8443
  proxy: none
  metrics:
    prometheusGrafana:
      grafanaPublicUrl: http://grafana.localhost:3000
  kafka: none

up reports the new addresses:

✓ metrics converged: grafana http://grafana.localhost:3000/d/quinectl-quine-37a6e0ca9274 (no login needed) — prometheus http://localhost:9090, scraping 2/2 members
  http://grafana.localhost:3000/d/quinectl-novelty-37a6e0ca9274
✓ quine is up: http://quine.localhost:8080
✓ novelty is up: http://novelty.localhost:8090

With auth on, Quine Enterprise and Novelty must have different hosts, because they share a session cookie name. quinectl refuses a file that gives both the same host.

quinectl token works as usual, and the token works at the new address:

curl -s -X POST http://quine.localhost:8080/api/v2/graph/quine/cypher:query \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $(quinectl token)" \
  -d '{"text":"RETURN 1"}'

With the reverse proxy

With the reverse proxy, publicUrl must use the proxy's scheme and port. With tls: true, also set secureCookies: true, because everything is on HTTPS:

quinectl.yaml
quine:
  edition: enterprise
  publicUrl: https://quine.localhost:18000
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
services:
  persistor: cassandra
  auth:
    keycloak:
      publicUrl: https://keycloak.localhost:8443
      secureCookies: true
  proxy:
    nginx:
      port: 18000
      tls: true
  metrics: none
  kafka: none

If your browser already shows a secure connection error

Once a browser has the error at localhost, every .localhost name fails in that browser too, because the HTTPS rule covers them all. Use .test names instead. Add them to /etc/hosts:

127.0.0.1 quine.test keycloak.test

Then use them in the file:

quinectl.yaml
quine:
  edition: enterprise
  publicUrl: http://quine.test:8080
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
services:
  persistor: cassandra
  auth:
    keycloak:
      publicUrl: https://keycloak.test:8443
  proxy: none
  metrics: none
  kafka: none

Changing a name

Edit quinectl.yaml and run quinectl up. The product restarts on its new address. A publicUrl is an origin only: http or https, a host, and an optional port, with no path or trailing slash.

Keycloak's address is shared by every project on the machine. If another project sets a different one, up replaces the Keycloak container and warns you.

Next steps