Skip to content

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 info should 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) and 8443 (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