Skip to content

Run Novelty

You can run Novelty on your own machine, on its own or beside Quine Enterprise, with the same local Cassandra, Keycloak auth, reverse proxy, metrics and Kafka that quinectl runs for Quine Enterprise. quinectl runs Novelty from a novelty: block in quinectl.yaml, as a single member.

Export your Novelty license

Novelty has its own license key and customer id. The customer id may differ from your Quine Enterprise one.

export NOVELTY_LICENSE_KEY=<your Novelty license key>
export NOVELTY_CUSTOMER_ID=<your thatDot customer id for Novelty>

Novelty on its own

A file for Novelty alone has a novelty: block and no quine: block. It doesn't need quine.edition, but the five services choices are still required. Save this as quinectl.yaml in a new directory:

quinectl.yaml
novelty:
  licenseKey: ${NOVELTY_LICENSE_KEY}
  customerId: ${NOVELTY_CUSTOMER_ID}
services:
  persistor: cassandra
  auth: keycloak
  proxy: none
  metrics: none
  kafka: none

Then start it:

quinectl up

Novelty runs on port 8080. For the same file with every option explained in place, run quinectl init --with-novelty, then delete the quine: block and the port: line in novelty:.

Novelty beside Quine Enterprise

To run both products from one file, write it with --with-novelty and start it:

quinectl init --with-novelty
quinectl up

The file has a novelty: block next to quine:. Novelty gets its own port (8090 in this file), its own Cassandra keyspace and, with auth on, its own Keycloak realm:

quinectl.yaml
quine:
  edition: enterprise
  port: 8080
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
novelty:
  port: 8090
  licenseKey: ${NOVELTY_LICENSE_KEY}
  customerId: ${NOVELTY_CUSTOMER_ID}
services:
  persistor: cassandra
  auth: keycloak
  proxy: none
  metrics: none
  kafka: none

With two products, up runs both in the background and returns once both are ready. It reports Quine Enterprise first, then Novelty, each with a ready line and a member table. This output keeps the ready lines and the line after them and leaves out the rest:

✓ quine is up: http://localhost:8080
✓ novelty is up: http://127.0.0.1:8090
→ browser sessions: quine at http://localhost:8080, novelty at http://127.0.0.1:8090 — both products set the same session cookie name, and cookies ignore ports, so use one host alias per product

With auth on, open each product at the address up prints; see Two products, two addresses.

quinectl status lists both members with a product column, and prints each realm's sample users. quinectl down stops both.

quinectl cass-reset deletes both products' keyspaces. Stop both with quinectl down first, because it refuses to run while either is running.

Calling Novelty's REST API

With auth on, the API needs a token from Novelty's realm. --product novelty mints one. For example, to list Novelty's models with both products running:

curl -s http://127.0.0.1:8090/api/v2/system/models \
  -H "Authorization: Bearer $(quinectl token --product novelty)"

With no models created yet, the response is:

{"items":[]}

Use the Novelty address up printed. Without --product, quinectl token signs in to Quine Enterprise when both are declared, and Novelty answers 401.

The full API is described in the Novelty REST API reference.

What Novelty gets from each service

Service For Novelty
Cassandra Its own keyspace, novelty.keyspace (default novelty), on the same Cassandra as Quine Enterprise
Keycloak Its own realm, novelty.realm (default novelty), with its own roles and sample users
Metrics Prometheus collects from it, and Grafana has a Novelty dashboard
Reverse proxy One proxy fronts one product: set services.proxy.nginx.target: novelty
Kafka Any declared topic can feed a Novelty ingest, which you write yourself

Running a Novelty distribution

To run a Novelty distribution you already have instead of the image, you need Java 17 or newer on your PATH, and the unpacked distribution: novelty.jar with its lib/ directory beside it. Set runtime: jar, point jar: at the file, and leave out customerId, because quinectl refuses it with a jar:

quinectl.yaml
novelty:
  runtime: jar
  jar: /opt/novelty/novelty.jar
  licenseKey: ${NOVELTY_LICENSE_KEY}
services:
  persistor: cassandra
  auth: keycloak
  proxy: none
  metrics: none
  kafka: none

See Image or jar for how the two runtimes differ.

Next steps