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.
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:
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:
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:
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:
uponly adds and updates. - To drop a product or cluster members you removed, run
quinectl down, thenquinectl up. - This project's proxy container stays until
quinectl down, thenquinectl down --rm. Thatdown --rmalso 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 gcoffers to remove it. - Changing Cassandra's
imageorcqlPortreplaces the container without asking, and empties every project's graph. See Graph Storage. - Cassandra keeps the
heapit was created with. To apply a new one, runquinectl down, thenquinectl down --rm, thenquinectl 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 --pullpulls it again for one run.pullPolicy: alwayspulls on every run, andpullPolicy: neverrefuses 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, removecustomerId, 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:
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:
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¶
- Set a product option quinectl has no field for: Passing Settings Through.
- Choose users and roles: Auth and RBAC with Keycloak.
- Find the guide for any other part of the file: Guides.