Skip to content

Configure quinectl

You choose what quinectl runs, from graph storage and auth to Kafka and metrics, in one file, quinectl.yaml, in your project directory. Edit it and run quinectl up, and quinectl starts what is missing, restarts what changed, and leaves running what already matches.

Start from a generated file

quinectl init writes a complete, commented file that runs as written:

quinectl init                  # Quine Enterprise
quinectl init --with-novelty   # Quine Enterprise and Novelty
quinectl init --minimal        # the same settings, without the comments

Nearly every option appears in the file with an explanation and its default, most of them commented out. Uncomment what you want to change; the quinectl.yaml Reference lists them all. quinectl init won't replace an existing file; pass --force to start over.

quinectl generate-config prints the same file, or writes it with -o to a path you choose. Use it to write the file somewhere else, or to compare your quinectl.yaml with a fresh one:

mkdir -p other
quinectl generate-config -o other/quinectl.yaml
quinectl generate-config | diff - quinectl.yaml

The six required choices

A quinectl.yaml must state these six choices, even when you want the default. A file missing one is rejected before anything starts, with a message naming the missing field and its allowed values.

quinectl.yaml
quine:
  edition: enterprise          # or: oss
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
services:
  persistor: cassandra         # or: rocks-db, in-memory
  auth: keycloak               # or: none
  proxy: none                  # or: nginx
  metrics: none                # or: prometheus-grafana
  kafka: none                  # or: local
Choice Guide
quine.edition This page; Run Novelty for Novelty
services.persistor Graph Storage
services.auth Auth and RBAC with Keycloak
services.proxy Reverse Proxy
services.metrics Metrics
services.kafka Kafka

quine.edition is required only when the file has a quine: block. A file that runs Novelty alone has a novelty: block and no quine: block.

Each service you turn on has a short form and a long form. The short form is one value, and uses every default for that service:

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

The long form replaces the value with a block of settings. Here Cassandra gets a larger heap:

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

In the long form, rocks-db, in-memory and prometheus-grafana are written rocksDb, inMemory and prometheusGrafana. Every field and its default is listed in the quinectl.yaml Reference.

Values from the environment

A value written as ${NAME} is read from the environment variable NAME when quinectl runs, so it never sits in the file. ${NAME} works only as a field's whole value, in licenseKey, customerId, user passwords, values under properties and jvmProperties, and an external Keycloak's adminUser and adminPassword. Other fields take their value as written. This file reads the license key and customer id from the environment:

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

If a variable the file refers to is unset or empty, quinectl stops with an error naming it. The customer id is the exception: quinectl reads it only when it pulls an image, so it can stay unset while the image is already on the machine.

How changes take effect

Run quinectl up after any change. quinectl compares what the file asks for with what is running:

  • A service that is already running and matches is reused untouched.
  • A missing service is started.
  • A product whose generated configuration changed is restarted with the new configuration. An unchanged product keeps running.
  • Anything you remove from the file keeps running: up only adds and updates.
  • To drop a product or cluster members you removed, run quinectl down, then quinectl up.
  • This project's proxy container stays until quinectl down, then quinectl down --rm. That down --rm also removes the shared Cassandra, Keycloak, Kafka and metrics containers, and the graph with Cassandra, when no other project uses them; see Stopping and removing.
  • A Kafka topic stays until quinectl gc offers to remove it.
  • Changing Cassandra's image or cqlPort replaces the container without asking, and empties every project's graph. See Graph Storage.
  • Cassandra keeps the heap it was created with. To apply a new one, run quinectl down, then quinectl down --rm, then quinectl up. That removes the graph.

Running quinectl up twice in a row with no change does nothing the second time.

To see what quinectl would hand each product without launching anything:

quinectl generate-quine-conf --dry-run
cat conf/quine/member-0.conf

--dry-run writes the configuration and starts nothing, so you can read what each product will be given. It never pulls, so with runtime: docker the product image must already be on the machine. With auth: keycloak, the file holds a placeholder client secret until Keycloak has been started once. Without --dry-run, generate-quine-conf also starts the services and pulls the product images, so a later up starts at once.

Image or jar

By default each product runs from its Docker image (runtime: docker), so you don't need Java or a product download. The Quine Enterprise and Novelty images come from registry.license.thatdot.com, pulled with your customer id and license key.

  • An image is pulled only when it isn't already on the machine. quinectl up --pull pulls it again for one run. pullPolicy: always pulls on every run, and pullPolicy: never refuses to pull unless you pass --pull.
  • image: runs a different tag, or a copy of the image in your own registry. quinectl pulls from any registry other than thatDot's without signing in. For an image on another registry, remove customerId, because quinectl refuses it there.

Use an image that is already on the machine

quinectl starts whatever image Docker already has under that name, and needs no customer id to do it. quinectl doesn't use the credentials Docker stores from docker login, so if your shell is already signed in to a registry, pull the image yourself and quinectl uses it from then on:

docker pull registry.license.thatdot.com/thatdot/quine-enterprise:2.2.1
quinectl up

This is also how to run from a private registry of your own that needs a sign-in: pull it with docker pull, then set image: to the same name and remove customerId. Keep pullPolicy at its default, missing, or set it to never so no run tries to pull.

To run a product distribution you already have instead, set runtime: jar. You need Java 17 or newer on your PATH, and the unpacked distribution: quine-enterprise.jar or novelty.jar with its lib/ directory beside it. Remove customerId from the block, because quinectl refuses it with a jar. Run quinectl from that directory, or point jar: at the file:

quinectl.yaml
quine:
  edition: enterprise
  runtime: jar
  jar: /opt/quine-enterprise/quine-enterprise.jar
  licenseKey: ${QE_LICENSE_KEY}
services:
  persistor: cassandra
  auth: keycloak
  proxy: none
  metrics: none
  kafka: none

quinectl checks that the jar or image really is the edition you declared, and stops if it isn't.

Logging

Each product's log level and redaction can be set in its block:

quinectl.yaml
quine:
  edition: enterprise
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
  logLevel: DEBUG           # ERROR, WARN (default), INFO, DEBUG, or TRACE
  logRedaction: false       # default; true hides ingested values in logs
  logShowExceptions: true   # default; false hides most exception details
services:
  persistor: cassandra
  auth: keycloak
  proxy: none
  metrics: none
  kafka: none

For local development quinectl turns redaction off by default, which differs from the products' own default.

Each member's output goes to logs/<product>/member-<n>.log in your project directory, whether it runs from an image or a jar. For a member running from an image, docker logs <container> shows the same output; up prints the container name.

Next steps