Payara Qube Documentation

Premium Support

Payara Qube
Edit this Page

Payara Qube Installation Guide

Overview

This guide walks you through the complete installation of Payara Qube on AWS.

By the end of it, you will be able to:

  • Prepare DNS,

  • Generate the installation bundle

  • Deploy the infrastructure with Pulumi and

  • Complete the initial post-install configuration

The wizard generates an Infrastructure-as-Code (IaC) project that uses Pulumi (an automation platform similar in concept to Terraform) to create all required AWS resources. You run the generated Pulumi project to install Payara Qube in your own AWS account.

Prerequisites

Before you start, make sure you have:

  • An AWS account with sufficient permissions to create Route 53 zones and infrastructure resources.

  • AWS CLI installed and configured on the machine you will use for the installation.

  • A Payara Nexus account with access to the Qube artifacts (listed in your welcome pack).

  • Pulumi installed locally (install it in Windows or WSL if you are using Windows).

  • Node.js and npm.

  • An SMTP server and credentials so Qube can send email (for example, Gmail with an app password).

  • A domain to dedicate to Qube. If you cannot delegate the full domain to AWS, plan a subdomain that you can manage via Route 53.

  • Helm (only needed if the deployment process prompts you for it).

DNS changes can take time to propagate. If you are pointing a domain or subdomain to AWS Route 53, allow extra time (up to 24 hours) before you run the Pulumi deployment.

Step 1: Prepare Your Domain

Payara Qube requires two DNS zones: one for the control plane and one for applications. You can either delegate an entire domain to AWS or keep the parent domain with your current registrar and delegate only the required subdomains to AWS.

Option 1: Delegate the Entire Domain to AWS (Recommended)

  1. Sign in to the AWS console and open Route 53.

  2. Choose Hosted zones and select Create hosted zone.

  3. Enter your domain name (for example, example.com), leave Description empty, select Public hosted zone, and click Create hosted zone.

  4. Note the four name servers listed in the Value/Route traffic to column (for example, ns-1147.awsdns-15.org.).

  5. Update the name server records at your domain registrar so they match the values provided by AWS.

Option 2: Use a Subdomain Without Delegating the Parent Domain

  1. In Route 53, create a hosted zone for the control plane (for example, qube.example.com).

  2. Note the AWS name servers for this hosted zone.

  3. Create a second hosted zone for the applications (for example, apps.qube.example.com) and note its name servers.

  4. Link the hosted zones:

    1. Open the control plane hosted zone.

    2. Choose Create record.

    3. Set Record name to apps (resulting in apps.qube.example.com), choose the NS record type, paste the four name servers from the application zone, optionally set TTL to 60, and click Create records.

  5. Update DNS at your registrar so the subdomain (for example, qube.example.com) points to the AWS name servers for the control plane zone.

  6. If your registrar requires one record per name server, create four individual NS records.

Verify DNS Propagation

Use dig to confirm that the NS records are visible on the public internet:

dig qube.example.com ns

You should see all four AWS name servers listed in the answer section before continuing.

Step 2: Generate the Installation Bundle

Use the Payara Qube wizard to collect your installation bundle.

  1. Navigate to https://billing.payara.cloud/install-qube/wizard (see your welcome pack for the exact URL) and authenticate with your Nexus credentials.

    Nexus Credentials Page
    Figure 1. Nexus Credentials Page

  2. Give the installation a descriptive name. This value becomes your Pulumi stack name and prefixes the AWS resources that will be created.

    Installation Name Definition Page
    Figure 2. Installation Name Definition Page

  3. Configure the DNS values. Use the zones you created earlier and append the stack name where required.

    DNS Definition Page
    Figure 3. DNS Definition Page
    Field Example (stack name: turn, domain: qube.example.com)

    Control Plane Domain

    turn.qube.example.com

    Control Plane DNS Zone

    qube.example.com

    Application Domain

    turn.apps.qube.example.com

    Application DNS Zone

    apps.qube.example.com

    Let’s Encrypt Contact Email

    admin@example.com

    Ensure that the Control Plane DNS Zone and Application DNS Zone exactly match the Route 53 hosted zones you created.

  4. Provide SMTP settings so Qube can send email.

    SMTP Definition Page
    Figure 4. SMTP Definition Page

    If you are using Gmail, configure SMTP similar to the following (replace with your details):

    • SMTP From: youremailaddress@gmail.com

    • SMTP Host: smtp.gmail.com

    • SMTP Port: 587

    • SMTP Username: youremailaddress@gmail.com

    • SMTP Password: Your Gmail app password

    • Use TLS: Yes

  5. Review the default cluster settings. Leave the defaults unless you have a specific requirement. Avoid reducing the instance size below the defaults, as that can cause deployment timeouts.

    Default Instance Definition Page
    Figure 5. Default Instance Definition Page

  6. Choose the AWS region where you want to deploy Qube. If you are adding an additional region to an existing Qube deployment, reuse the same stack name.

    Installation Region Definition Page
    Figure 6. Installation Region Definition Page

  7. Click Generate installation data to download the installation zip file.

Step 3: Prepare the Installation Workspace

  1. Move the downloaded zip file into an empty directory (for example, ~/qube) and unzip it.

    mkdir -p ~/qube
mv ~/Downloads/qube-installation.zip ~/qube/
cd ~/qube
unzip qube-installation.zip

  2. Verify that the directory contains files similar to the following (the stack name in Pulumi.<stack>.yaml matches the name you entered in the wizard):

    .npmrc  Pulumi.turn.yaml  Pulumi.yaml  index.ts  node_modules  package-lock.json  package.json  tsconfig.json

  3. Decide where Pulumi will store its state and log in accordingly:

    Pulumi keeps a state file that tracks every resource it creates so it can calculate updates safely. Pulumi Cloud hosts this state for you, while the local and self-managed options store it elsewhere.

    		 
    # Pulumi Cloud (recommended)
pulumi login

# Azure Blob storage (example)
pulumi login azblob://pulumi/?storage_account=stacc

# Local filesystem (use only for short-lived evaluation)
pulumi login --local

  4. Inspect the extracted .npmrc. If it contains a Payara Nexus entry, copy the line into your global ~/.npmrc so that npm install can download the private Qube packages without prompting for credentials.

Step 4: Deploy with Pulumi

  1. Install the project dependencies:

    pulumi install

  2. Initialize the Pulumi stack (replace turn with your stack name) and synchronise the configuration:

    pulumi stack init turn
pulumi refresh -y

  3. Start the deployment:

    pulumi up

The first run downloads containers, provisions AWS infrastructure, and can take 45 minutes or more. Because AWS and Kubernetes are eventually consistent, you may need to re-run pulumi up if the first attempt reports transient errors.

When the deployment finishes, Pulumi prints the outputs you will use to access Qube. You can retrieve them again at any time (including secrets) with:

pulumi stack output --show-secrets

The command returns the Keycloak URL, Payara Qube management URL, and initial administrative credentials.

Step 5: Post-Install Tasks

  • Sign in to the Keycloak admin interface (userManagementUrl) with the temporary administrator credentials provided in the Pulumi outputs.

  • Create a permanent administrator:

    • Go to Users → Add user, fill in the details, and create the user.

    • Open the new user, choose Credentials, set a strong password, and disable the Temporary flag.

    • In Role Mapping, assign the realm admin role.

  • Optionally disable the bootstrap administrator once the permanent account is confirmed.

  • Follow the Payara Qube Organisation Management guide to create your first organisation, invite users, and configure namespaces.

Troubleshooting

AWS credentials error

error: unable to validate AWS credentials

Verify your credentials with aws sts get-caller-identity and ensure you are targeting the correct AWS account.

Helm release timeout

error: Helm release failed to initialize completely

Run pulumi up again. If the problem persists, inspect the release with the Helm CLI or the Kubernetes dashboard.

Domain resolution issues

qb02-import-realm failing/timing out

Confirm that both control plane and application domains resolve publicly and that the TLS certificate is valid at https://users.control.plane.domain.example.

General deployment retries

If a deployment step fails due to eventual consistency, rerun pulumi up. Pulumi will converge the stack to the expected state.