Quick Start¶
By the end of this page, Quine Enterprise is running on your own machine with Keycloak auth, and you have called its REST API with a bearer token. It takes a few minutes, most of it the first image downloads.
Before you start¶
- quinectl is installed. See Get quinectl.
- Docker is running. quinectl talks to the Docker engine directly, so
docker infoshould succeed. You don't need Java. - Docker has memory to spare. Quine Enterprise, Cassandra and Keycloak together use about 3.5 GB, and more as the graph grows.
- Ports
8080(Quine Enterprise),9042(Cassandra) and8443(Keycloak) are free.
1. Export your license¶
quinectl reads your license key and customer id from the environment. It needs the customer id only to pull the Quine Enterprise image, as the registry username.
export QE_LICENSE_KEY=<your license key>
export QE_CUSTOMER_ID=<your thatDot customer id>
2. Create a configuration¶
Make a directory for the project and let quinectl write a starting quinectl.yaml into it:
mkdir my-quine && cd my-quine
quinectl init
It confirms the file and says what to do next:
✓ wrote quinectl.yaml
→ next: edit quinectl.yaml to customize (every option is explained in place), then run 'quinectl up'
→ enterprise needs its license key exported first, and your thatDot customer id to pull the image:
export QE_LICENSE_KEY=<your key>
export QE_CUSTOMER_ID=<your thatDot customer id> # only to pull the image
→ then run 'quinectl trust' once so your browser trusts the local CA (enterprise auth login)
The file runs as written: Quine Enterprise from its image, a Cassandra container for the graph, and Keycloak for auth. Every other Quine Enterprise and service option is in the file, commented out, with an explanation. You don't need to change anything for this walkthrough.
3. Start everything¶
Start the services and Quine Enterprise:
quinectl up
quinectl pulls the images it needs, starts Cassandra and Keycloak, creates the Keycloak realm and sample
users, writes the Quine Enterprise configuration, and launches Quine Enterprise. Once Quine Enterprise
is ready, up returns and Quine Enterprise keeps running in the background. Its output goes to
logs/quine/member-0.log.
The output looks like this:
✓ cassandra converged (owned, CQL ready)
✓ keycloak converged (owned, admin ready; CA: ~/.quinectl/state/certs/ca.pem)
✓ keycloak realm quine-enterprise converged
✓ keycloak users (quine-enterprise): created superadmin1, created sre1, created architect1, created dataengineer1, created analyst1, created billing1
→ rendering config
✓ wrote conf/quine/member-0.conf
→ launching registry.license.thatdot.com/thatdot/quine-enterprise:2.2.1 (log: logs/quine/member-0.log or `docker logs quinectl-quine-c215e477022f-0`)
→ waiting for quine readiness (port 8080)…
✓ quine is up: http://localhost:8080
idx web url conf log state
0 http://localhost:8080 conf/quine/member-0.conf logs/quine/member-0.log ready
→ verify: curl -s -o /dev/null -w '%{http_code}' http://localhost:8080/api/v2/system/readiness # expect 204
→ query: curl -s -X POST http://localhost:8080/api/v2/graph/quine/cypher:query -H 'Content-Type: application/json' -d '{"text":"RETURN 1"}' # needs -H "Authorization: Bearer $(quinectl token)"
→ login: quinectl token # prints a sample-user bearer token (see 'quinectl status' for the seeded users)
The progress lines vary from run to run. When Cassandra or Keycloak isn't already running, up also
prints → converging cassandra or → converging keycloak while it starts them. Their lines can come in
either order. The first run also prints a → pulling … line for each image it downloads, and a slow
start adds still waiting lines. The container name differs on your machine. The last lines are commands you
can copy to check the running product.
4. Trust the local certificate (macOS)¶
On Linux and Windows, skip to step 5: quinectl trust works only on macOS, and your browser shows a
certificate warning on the sign-in page that you can accept.
Keycloak serves its sign-in page over HTTPS with a certificate from a local certificate authority that quinectl creates. To let your browser open it without a warning, add the certificate authority to your login keychain once per machine:
quinectl trust
It asks you to confirm before changing the keychain. Safari and Chrome then accept the sign-in page. Firefox keeps its own certificate list and shows a warning instead. For Firefox, and for importing the certificate on Linux and Windows, see Auth and RBAC with Keycloak.
5. Sign in¶
Open http://localhost:8080 and sign in with one of the sample users. To see them, run quinectl status:
quinectl status
The end of its output lists the sample users:
sample users:
username password roles
superadmin1 superadmin123 SuperAdmin
sre1 sre123 SRE
architect1 architect123 Architect
dataengineer1 dataengineer123 DataEngineer
analyst1 analyst123 Analyst
billing1 billing123 Billing
caveat: dev credentials — local development only
There is one user per Quine Enterprise role. Signing in as each one shows what that role can do.
6. Call the REST API¶
With auth on, the REST API needs a bearer token. Without one, a query is refused:
curl -s -X POST http://localhost:8080/api/v2/graph/quine/cypher:query \
-H 'Content-Type: application/json' \
-d '{"text":"RETURN 1"}'
The response is a 401:
{"error":{"code":401,"status":"UNAUTHENTICATED","message":"Missing session cookie or access token.","details":[]}}
quinectl token prints a token for the first sample user, superadmin1. Put it in the request:
curl -s -X POST http://localhost:8080/api/v2/graph/quine/cypher:query \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $(quinectl token)" \
-d '{"text":"RETURN 1"}'
The response holds the query's result:
{"columns":["1"],"results":[[1]]}
Tokens last five minutes, so call quinectl token inside each command as shown rather than saving
one. quinectl token --user analyst1 signs in as a different user. The full REST API is described in
the Quine Enterprise REST API reference.
7. Stop¶
Stop Quine Enterprise:
quinectl down
The output names the container it stopped, which differs on your machine:
✓ stopped quine member container quinectl-quine-c215e477022f-0
This stops Quine Enterprise and nothing else. Cassandra and Keycloak keep running, with your graph and
users, so the next quinectl up is quick. To stop those too, see
Stopping and removing in Multi-tenancy.
quinectl down --all --purge removes every project's data
It removes everything quinectl has started on this machine, with every project's graph, Keycloak
users and Kafka topics. To see what it would remove without removing anything, run
quinectl down --all --purge --dry-run. To remove quinectl itself as well, see
Uninstall quinectl.
Next steps¶
- Change what runs: Configure quinectl.
- Add Novelty: Run Novelty.
- Load data from Kafka: Kafka.
- Run Quine OSS instead, with no license key, by starting from
quinectl init --edition oss. - Look up an error message: Troubleshooting.