Self-Hosted Deployment Guide

This guide walks you through deploying Qualytics in your own Kubernetes environment.

Deployment Overview

A self-hosted Qualytics deployment consists of the following steps:

flowchart LR
    A[1. Provision\nInfrastructure] --> B[2. Configure\nKubernetes]
    B --> C[3. Deploy via\nHelm Chart]
    C --> D[4. Configure\nAuthentication]
    D --> E[5. Configure\nDNS and TLS]
    E --> F[6. Verify\nDeployment]
    F --> G[7. Activate\nLicense]

Prerequisites

Before you begin, ensure you have the following:

Qualytics-Provided Configuration

Qualytics sends the following items through an agreed secure channel before installation or upgrade:

The platform license is a separate artifact requested after installation.

Step 1: Provision Infrastructure

Qualytics supports Kubernetes clusters hosted on AWS (EKS), GCP (GKE), Azure (AKS), and CNCF-compliant on-premises distributions.

Node Requirements

The standard topology uses nodes with the following labels:

Step 2: Configure Kubernetes

Create Namespace and Registry Secret

Create the image pull Secret with the registry token provided by Qualytics. The prompt keeps the token out of your shell history.

kubectl create namespace qualytics
printf "Qualytics registry token: "
IFS= read -rs QUALYTICS_REGISTRY_TOKEN
echo
kubectl create secret docker-registry regcred \
  --namespace qualytics \
  --docker-username qualyticsai \
  --docker-password "$QUALYTICS_REGISTRY_TOKEN"
unset QUALYTICS_REGISTRY_TOKEN

printf "Qualytics registry token: "
IFS= read -rs QUALYTICS_REGISTRY_TOKEN
echo
printf '%s' "$QUALYTICS_REGISTRY_TOKEN" | docker login \
  --username qualyticsai \
  --password-stdin
unset QUALYTICS_REGISTRY_TOKEN

Step 3: Deploy via Helm Chart

Add the Qualytics Helm Repository

helm repo add qualytics https://qualytics.github.io/qualytics-self-hosted
helm repo update

Create Your Configuration File

Download the template from the release tag that matches the chart version approved by Qualytics. This keeps the available settings and image references aligned with the release you install.

CHART_VERSION="<version provided by Qualytics>"
curl --fail --location \
  "https://raw.githubusercontent.com/Qualytics/qualytics-self-hosted/qualytics-${CHART_VERSION}/template.values.yaml" \
  --output values.yaml
chmod 600 values.yaml

Do not commit or share a populated values.yaml. GitOps users should store sensitive values with their organization's encrypted secret-management workflow.

Configure Required Values

Deployment identifier

Paste the identifier provided by Qualytics exactly as received. Do not base64-encode it or reuse it for another deployment.

secrets:
  deployment:
    identifier: "<provided by Qualytics>"

DNS record

global:
  dnsRecord: "your-company.qualytics.io"

Authentication

Choose one authentication mode:

global:
  authType: "OIDC"

secrets:
  oidc:
    oidc_discovery_url: "https://your-idp.example.com/.well-known/openid-configuration"
    oidc_client_id: "your-oidc-client-id"
    oidc_client_secret: "your-oidc-client-secret"
  auth:
    jwt_signing_secret: "your-secure-jwt-secret"

global:
  authType: "AUTH0"

secrets:
  auth0:
    auth0_audience: "your-api-audience"
    auth0_organization: "org_your-org-id"
    auth0_spa_client_id: "your-spa-client-id"
  auth:
    jwt_signing_secret: "your-secure-jwt-secret"

Service credentials

Generate a different secure random value for each credential.

secrets:
  auth:
    jwt_signing_secret: "your-secure-jwt-secret"  # Minimum 32 characters
  postgres:
    secrets_passphrase: "your-secure-passphrase"
  rabbitmq:
    rabbitmq_password: "your-secure-password"

Use openssl rand -base64 32 to generate each value.

Optional configuration

• Set nginx.enabled: true if you need the chart to install an ingress controller.
• Set ingress.enabled: true to create the Qualytics ingress resources.
• Provide an existing Kubernetes TLS Secret for ingress encryption. The chart does not issue TLS certificates.
• Configure SMTP for email notifications, invitations, and password resets. See the SMTP Configuration Guide.

To inspect every setting for the selected release, run:

helm show values qualytics/qualytics --version "$CHART_VERSION"

Database Configuration (Optional)

Qualytics can use the PostgreSQL instance included with the chart or an external PostgreSQL-compatible database. Set connection credentials in secrets.postgres and set postgres.enabled: false when using an external database.

The default PostgreSQL schema is public. To use another schema, set:

postgres:
  schema: "qualytics"

For an external database, ask your database administrator to create the schema and grant the Qualytics database user the required permissions before installation. Changing postgres.schema after installation does not move existing tables. Plan and complete a database migration before changing it for an existing deployment.

Deploy

Use the exact chart version approved by Qualytics.

CHART_VERSION="<version provided by Qualytics>"

helm upgrade --install qualytics qualytics/qualytics \
  --namespace qualytics \
  --create-namespace \
  --version "$CHART_VERSION" \
  -f values.yaml \
  --wait \
  --timeout=20m

Monitor Deployment

kubectl get pods -n qualytics

Wait until the expected application pods show a Running status before proceeding.

Step 4: Configure Authentication

Qualytics supports two authentication modes for self-hosted deployments:

• OIDC Configuration Guide
• Auth0 Setup Guide

Step 5: Configure DNS and TLS

Get the ingress IP address from your deployment:

# If using the included ingress controller
kubectl get svc -n qualytics qualytics-nginx-controller

# Or check ingress resources
kubectl get ingress -n qualytics

Configure DNS

Use one of these options.

Option A: Qualytics-Managed DNS (Recommended)

For a hostname under qualytics.io, send the ingress IP address to your Qualytics account manager so Qualytics can configure the DNS record.

Option B: Custom Domain

For your own domain, create a DNS record that points to the ingress IP address.

Set global.dnsRecord in values.yaml to the resulting hostname.

Configure TLS

The chart uses an existing Kubernetes TLS Secret and does not install a certificate issuer. Obtain a certificate for the configured hostname through your organization's approved process, then create the Secret in the release namespace:

kubectl create secret tls qualytics-tls-cert \
  --namespace qualytics \
  --cert=./fullchain.pem \
  --key=./privkey.pem

Reference the Secret in values.yaml:

ingress:
  enabled: true
  tls:
    secretName: "qualytics-tls-cert"

See Ingress TLS Configuration for additional options.

Step 6: Verify Deployment

1. Check pod health. Verify that all pods are running:

   kubectl get pods -n qualytics
   

2. Check API health. Verify that the API responds:

   curl --fail https://your-company.qualytics.io/api/health
   

3. Test authentication. Open the configured domain and sign in with OIDC or Auth0.

Step 7: Activate Your License

Self-hosted deployments require a valid license. A 31-day grace period starts when you create the first datastore connection. During the grace period, the platform is fully functional without a signed license. The Settings > Status page shows the remaining time.

Requesting a License

1. Sign in with the Admin role and open Settings > Status.
2. Select Generate License Request.
3. Send the request to your Qualytics account manager through the agreed secure channel. Do not send it in ordinary email.
4. Qualytics returns a signed license.

Applying a License

1. In Settings > Status, select Update License.
2. Paste the signed license and submit it.
3. Confirm that the Status page shows the expected expiration date.

Renewal

Generate a new request, send it to Qualytics through the agreed secure channel, and apply the returned signed license.

• A warning appears when the license expires within 30 days.
• Renew before expiration to avoid interruption to new data operations.

Air-Gapped Deployments

Qualytics can run without internet egress after the approved release artifacts are available inside your environment.

1. Obtain the approved chart archive, matching configuration template, and image list through your agreed delivery process.
2. Mirror every image required by that chart version into a registry reachable from the cluster. Use docs/docker-images.md from the same release tag as the checklist.
3. Update all image URLs and registry credentials in your secure configuration.
4. Install from the local chart archive instead of the online Helm repository.
5. Use OIDC and ensure the cluster can reach your identity provider.

The deployment identifier is still required. Auth0 requires access to auth.qualytics.io, so it is not suitable for an environment with no internet egress.

Upgrading

Update the Helm Repository

Add the Helm repository if needed, refresh it, and list available versions:

helm repo add qualytics https://qualytics.github.io/qualytics-self-hosted
helm repo update
helm search repo qualytics/qualytics --versions

Use the exact target version approved by Qualytics. Download its template for comparison, but do not overwrite your populated values file:

CHART_VERSION="<version provided by Qualytics>"
curl --fail --location \
  "https://raw.githubusercontent.com/Qualytics/qualytics-self-hosted/qualytics-${CHART_VERSION}/template.values.yaml" \
  --output "template.values.${CHART_VERSION}.yaml"

Review new and changed settings, then apply them to your existing values.yaml. Keep the deployment identifier unchanged.

Run the Upgrade

helm upgrade --install qualytics qualytics/qualytics \
  --namespace qualytics \
  --version "$CHART_VERSION" \
  -f values.yaml \
  --wait \
  --timeout=20m

Monitor Upgrade Progress

kubectl get pods --namespace qualytics --watch

Watch until the upgraded application pods are running.

Verify the Upgrade

Confirm that the application is accessible, authentication succeeds, and the API health endpoint responds.

Troubleshooting

Common Issues

Missing Deployment Identifier

If Helm reports secrets.deployment.identifier is required, confirm that the value is present at the exact path shown below:

secrets:
  deployment:
    identifier: "<provided by Qualytics>"

Paste the value exactly as Qualytics provided it. Do not base64-encode it. Contact your Qualytics account manager if you have not received an identifier for this deployment.

Pods Stuck in Pending State

• Check node resources: kubectl describe nodes
• Verify that node selectors match your cluster labels.
• Ensure the configured storage classes are available.

Image Pull Errors

• Confirm that the registry Secret exists: kubectl get secret regcred -n qualytics
• Inspect the affected pod's events: kubectl describe pod <pod-name> -n qualytics
• Confirm that the cluster can reach the configured registry and that the token has not expired.

Ingress Not Working

• Ensure an ingress controller is installed and running.
• Check the ingress resources: kubectl describe ingress -n qualytics
• Confirm that the TLS Secret exists: kubectl get secret qualytics-tls-cert -n qualytics

Authentication Errors

• For OIDC issues, see OIDC troubleshooting.
• For Auth0 issues, verify the supplied values with your Qualytics account manager.

Useful Commands

# Check all resources
kubectl get all -n qualytics

# View logs for a specific pod
kubectl logs -f <pod-name> -n qualytics

# View processing driver logs
kubectl logs -f deployment/qualytics-spark -n qualytics

# View detailed pod information
kubectl describe pod <pod-name> -n qualytics