Skip to content

Deploy to EC2

To share a demo or an evaluation with your team, run quinectl on one EC2 instance behind an Application Load Balancer. The load balancer handles HTTPS with a real certificate, and publicUrl tells quinectl the addresses browsers use.

A shared demo, not production

This is still one machine running a development Keycloak, with a Grafana that signs in as admin / admin. Keep real data off it, and limit who can reach it. For production, see Kubernetes with Helm and Terraform on AWS.

How it fits together

Browsers reach an Application Load Balancer, which sends each of four hostnames to one port on a single EC2 instance. One security group limits the load balancer to your IP ranges, and a second limits the instance to the load balancer.

The load balancer ends HTTPS and routes each hostname to a port on the instance. These examples use demo.example.com; use a domain of your own.

Hostname Instance port Protocol to the instance Health check
quine.demo.example.com 8080 HTTP GET /api/v2/system/readiness returns 204
novelty.demo.example.com 8090 HTTP GET /api/v2/system/readiness returns 204
keycloak.demo.example.com 8443 HTTPS GET /realms/master returns 200
grafana.demo.example.com 3000 HTTP GET /api/health returns 200

Keycloak serves a certificate from quinectl's local certificate authority, which the load balancer doesn't verify.

1. Create the AWS resources

Create these in order, because each one uses the ones before it.

  1. Network: a VPC with an internet gateway, and two public subnets in different Availability Zones. A load balancer needs at least two.
  2. Security groups: create two, one for the load balancer and one for the instance.

    Security group Inbound Outbound
    Load balancer 80 and 443, from your own IP ranges only Leave the default
    Instance 8080, 8090, 8443 and 3000, from the load balancer's group only Leave the default

    Keep the instance's other ports closed, because quinectl also publishes Cassandra, Prometheus and any Kafka broker there. The instance needs its outbound access to pull images, reach the license server and connect to Session Manager. If you limit the load balancer's outbound rules, still allow it to reach the instance's group on these ports, for traffic and health checks.

  3. Instance: Amazon Linux 2023 on x86-64, in a public subnet with a public IP address and the instance security group. Give it an instance role with the AmazonSSMManagedInstanceCore policy, so you can connect with AWS Systems Manager Session Manager. You don't need SSH or a key pair.

    An m6i.2xlarge with a 100 GB gp3 root volume is enough for this guide. It has been tested with more: a cluster of three members and one hot spare, plus Novelty, Keycloak, Kafka and metrics.

  4. Certificate: one AWS Certificate Manager certificate covering the four hostnames, in the same Region as the load balancer. Use DNS validation, and add the CNAME records it gives you. Route 53 can add them for you. Validation times out after 72 hours.

  5. Target groups: one for each row of the table above, with that row's port, protocol and health check, and the instance as its target. Targets stay unhealthy until you start quinectl.
  6. Load balancer: an internet-facing Application Load Balancer in both subnets, with the load balancer security group and a 300 second idle timeout. Give it two listeners:
    • HTTPS on 443: use the certificate, add one rule per hostname that forwards to its target group, and set a fixed 404 as the default action.
    • HTTP on 80: redirect to HTTPS.
  7. DNS: an alias record for each hostname, pointing at the load balancer.

2. Prepare the instance

Open a session on the instance, then install Docker:

sudo dnf install -y docker
sudo systemctl enable --now docker
sudo usermod -aG docker ec2-user

Switch to ec2-user, which picks up the group change, and run the remaining steps as that user:

sudo su - ec2-user

Install quinectl with the linux-amd64 build; see Get quinectl.

3. Write the configuration

Create a directory for the project, and put this quinectl.yaml in it, with your own hostnames:

quinectl.yaml
quine:
  edition: enterprise
  publicUrl: https://quine.demo.example.com
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
  users:
    - username: demo-admin
      password: ${DEMO_PASSWORD}
      roles: [SuperAdmin]
novelty:
  port: 8090
  publicUrl: https://novelty.demo.example.com
  licenseKey: ${NOVELTY_LICENSE_KEY}
  customerId: ${NOVELTY_CUSTOMER_ID}
  users:
    - username: demo-admin
      password: ${DEMO_PASSWORD}
      roles: [SuperAdmin]
services:
  persistor: cassandra
  auth:
    keycloak:
      publicUrl: https://keycloak.demo.example.com
      secureCookies: true
  proxy: none
  metrics:
    prometheusGrafana:
      grafanaPublicUrl: https://grafana.demo.example.com
      grafanaAnonymous: false
  kafka: none
  • publicUrl is the address browsers use. quinectl gives it to the product and to Keycloak, while its own checks and quinectl token stay on localhost.
  • users replaces the sample users, whose passwords are published in these docs. They can no longer sign in.
  • secureCookies: true keeps session cookies on HTTPS.
  • proxy: none is needed because the load balancer is the front door.
  • grafanaAnonymous: false makes Grafana ask for a sign-in.

Quine Enterprise and Novelty need different hostnames, because they share a session cookie name; see Two products, two addresses.

4. Start it

Set the keys and the demo password, then run up:

export QE_LICENSE_KEY=<your Quine Enterprise key>
export QE_CUSTOMER_ID=<your customer id>
export NOVELTY_LICENSE_KEY=<your Novelty key>
export NOVELTY_CUSTOMER_ID=<your customer id>
export DEMO_PASSWORD=<a password of your own>
quinectl up

up reports the public addresses:

✓ metrics converged: grafana https://grafana.demo.example.com/d/quinectl-quine-f8dec21d90ab (admin/admin) — prometheus http://localhost:9090, scraping 2/2 members
  https://grafana.demo.example.com/d/quinectl-novelty-f8dec21d90ab
✓ quine is up: https://quine.demo.example.com
✓ novelty is up: https://novelty.demo.example.com

If up warns that a host doesn't resolve, check the DNS records. It carries on either way.

5. Check it

Once the target groups are healthy, this prints 204:

curl -s -o /dev/null -w '%{http_code}\n' https://quine.demo.example.com/api/v2/system/readiness

Open https://quine.demo.example.com and sign in as demo-admin. Novelty's address works the same way.

For REST API calls, run quinectl token on the instance, then call the public address with the token:

curl -s -X POST https://quine.demo.example.com/api/v2/graph/quine/cypher:query \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $(quinectl token)" \
  -d '{"text":"RETURN 1"}'

The response looks like this:

{"columns":["1"],"results":[[1]]}

Run a cluster

To run a cluster, add cluster: under quine:, and put every member's port in the Quine Enterprise target group, such as 8080 to 8083 for three members and one hot spare. Open the same ports in the instance's security group, and turn on cookie stickiness for the target group.

A hot spare answers readiness with 503, so its target shows as unhealthy and gets no traffic. That is expected.

Before you share it

  • Grafana: it signs in as admin / admin, and that can't be changed: after a new password, every quinectl up fails with unexpected status 401. The IP limit on the load balancer is what protects it. To keep Grafana private, leave out its hostname, target group and security group rule.
  • Keycloak: its admin console is reachable through the load balancer, so the same limit protects it.
  • Secrets: the exported keys and password live in your session. A secret store such as AWS Systems Manager Parameter Store keeps them out of your shell history.

Change an address

Edit the publicUrl and run quinectl up. The product restarts on its new address, and Keycloak accepts it. Add the matching DNS record, certificate name and listener rule on the AWS side.

Stop it

quinectl down stops the products, and leaves Cassandra, Keycloak and your graph in place. To remove everything, see Stopping and removing. Delete the AWS resources when you're done, because the instance and load balancer cost money while they exist.

Next steps