Skip to content

AppControl Installation Guide for OpenShift

1. Introduction

This guide describes the installation process for AppControl on an OpenShift cluster. It covers Helm charts, configuration steps, and verification procedures.

2. Requirements

2.1 OpenShift Cluster

Ensure that you have an OpenShift cluster with a dedicated project (namespace) for deploying AppControl. If OpenShift is not running, start it with:

crc start

To create the namespace if it does not exist:

oc new-project Appcontrol || oc project Appcontrol

2.2 OpenShift Ingress (Default Router)

OpenShift includes an Ingress controller by default via its built-in Router (HAProxy). Instead of configuring an additional Ingress controller, we will use OpenShift's native Route system to expose the application.

2.3 SQL Server Database

AppControl requires a Microsoft SQL Server database.

  • Required version: SQL Server 2017+
  • Example connection string: Server=tcp:MY_SERVER_IP,1433;Initial Catalog=MYDATABASE;Persist Security Info=False;User ID=USERID;Password=PASSWORD;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30; This connection string will be required in the appcontrol_values.yaml file, which is used when deploying AppControl with Helm.

2.4 Redis

AppControl uses Redis for caching and persistent storage.

  • Installation Procedure:
 export REDIS_PASSWORD=mysecurepassword
 oc create secret generic redis-secret --from-literal=REDIS_PASSWORD="$REDIS_PASSWORD" -n appcontrol
     oc apply -f https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/refs/heads/main/docs/config/redis-pvc.yaml -n appcontrol
     oc apply -f https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/refs/heads/main/docs/config/redis-deployment.yaml -n appcontrol
     oc apply -f https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/refs/heads/main/docs/config/redis-service.yaml -n appcontrol

`

  • Verify Installation:
  oc get pods -n appcontrol
  oc logs deployment/redis -n appcontrol
  oc get svc redis -n appcontrol

Later in the configuration process, you will be notified to set REDIS_CONNECTION_STRING. The REDIS_CONNECTION_STRING is : redis:6379,password=$REDIS_PASSWORD

2.5 RabbitMQ

A RabbitMQ instance should be set up with a dedicated virtual host.

  • Example connection details: Host: YOUR_RABBIT_HOST Virtual Host: APPCONTROL_VIRTUAL_HOST User: YOUR_USERNAME Password: YOUR_PASSWORD

2.6 Configuring the AppControl Domain

Define a DNS entry for the AppControl platform.

If you are deploying elsewhere, ensure that this domain is properly configured.

  • Example domains:
    • AppControl: appcontrol.MyCompany.com

This domain will be used later in the configuration.

3. Platform Configuration

3.1 Helm Repository Setup

Before installing Helm charts, authenticate to the Helm registry using credentials provided by the AppControl editor:

helm registry login x4bcontainerregistry.azurecr.io --username login --password password

Set up the Helm repository:

REPO="oci://x4bcontainerregistry.azurecr.io/helm"

3.2 Application Configuration

The configuration templates for AppControl are available in the repository:

To use them in your deployment, replace MY_APPCONTROL_DOMAIN dynamically:


MY_APPCONTROL_DOMAIN="appcontrol.MyCompany.com"

oc create configmap appcontrol-config \
  --from-literal=applications.json="$(curl -s https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/refs/heads/main/docs/config/applications-template.json | sed "s/MY_APPCONTROL_DOMAIN/$MY_APPCONTROL_DOMAIN/g")" \
  --from-literal=services.json="$(curl -s https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/refs/heads/main/docs/config/services-template.json | sed "s/MY_APPCONTROL_DOMAIN/$MY_APPCONTROL_DOMAIN/g")"

3.3 JWT Secret Keys

The secret name used for JWT keys in OpenShift is jwt-keys. This name must be referenced later in the configuration.

Generate a self-signed certificate and create a secret for JWT keys:

openssl genpkey -algorithm RSA -out jwt-private.pem
openssl rsa -pubout -in jwt-private.pem -out jwt-public.pem

Then, create the secret in OpenShift:

oc create secret generic jwt-keys -n Appcontrol \
  --from-file=jwt-private.pem=jwt-private.pem \
  --from-file=jwt-public.pem=jwt-public.pem

4. Helm Chart Installation

4.1 Install AppControl Services

The configuration template for x4b-services-values.yaml is available in the repository:

To view all possible values before installing:

helm show values "$REPO/appcontrol-services"

Before installation, check the helm chart version. To install the services with customized values:

MY_APPCONTROL_DOMAIN="appcontrol.MyCompany.com"
MY_SECRET_NAME="jwt-keys"
YOUR_SQLSERVER_CONNECTION_STRING="your_sqlserver_connection_string"
CHART_VERSION=
helm install appcontrol-services "$REPO/appcontrol-services" \
  --namespace Appcontrol \
  --version "$CHART_VERSION" \
  -f https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/refs/heads/main/docs/config/x4b-services-values.yaml \
  --set externalHostname="x4b.$MY_APPCONTROL_DOMAIN" \
  --set jwtSecretName="$MY_SECRET_NAME" \
  --set sql.connectionString="$YOUR_SQLSERVER_CONNECTION_STRING" \
  --namespace Appcontrol

4.2 Install AppControl

helm install appcontrol "$REPO/appcontrol" \
  --namespace Appcontrol \
  -f appcontrol_values.yaml

To view all possible values before installing:

helm show values "$REPO/appcontrol-services"

Before installation, check the helm chart version.

To install the services with customized values:

MY_APPCONTROL_DOMAIN="appcontrol.MyCompany.com"
REDIS_CONNECTION_STRING=
HTTTPROTOCOL=https
CHART_VERSION=
YOUR_SQLSERVER_CONNECTION_STRING="your_sqlserver_connection_string"
RABBITMQ_HOST_NAME="Your rabbitmq host eg: rabbitmq.rabbitmq.svc.cluster.local"
RABBITMQ_USER="Your rabbitmq user"
RABBITMQ_PASSWORD="Your rabbitmq password"
RABBITMQ_VHOST="Your rabbitmq vhost"
# Download and replace all instances of MY_APPCONTROL_DOMAIN
curl -s https://raw.githubusercontent.com/xcomponent/appcontrol-documentation/refs/heads/main/docs/config/appcontrol_values.yaml \
  | sed "s/MY_APPCONTROL_DOMAIN/${MY_APPCONTROL_DOMAIN}/g" \
  | sed "s/HTTTPROTOCOL/${HTTTPROTOCOL}/g" \
  > /tmp/appcontrol_values.yaml

# Install using the updated YAML file
helm install appcontrol-services "$REPO/appcontrol-services" \
  --namespace Appcontrol \
  --version "$CHART_VERSION" \
  -f /tmp/appcontrol_values.yaml \
  --set jwtSecretName="$MY_SECRET_NAME" \
  --set redisConnectionString="$REDIS_CONNECTION_STRING" \
  --set dbaccess.connectionString="$YOUR_SQLSERVER_CONNECTION_STRING" \
  --set rabbitmq.hostname="$RABBITMQ_HOST_NAME" \
  --set rabbitmq.username="$RABBITMQ_USER" \
  --set rabbitmq.password="$RABBITMQ_PASSWORD" \
  --set rabbitmq.virtualHost="$RABBITMQ_VHOST" \
  --namespace Appcontrol

5. Exposing AppControl in OpenShift

5.1 Create an OpenShift Route

Instead of using an Ingress resource, OpenShift provides a built-in Router to expose services externally. To expose AppControl, create a Route:

oc expose svc/appcontrol --hostname=MY_APPCONTROL_DOMAIN

This will generate a public endpoint for AppControl.

5.2 Verify the Created Route

Check if the Route has been created successfully:

oc get routes

Example output:

NAME          HOST/PORT                 PATH   SERVICES      PORT   TERMINATION   WILDCARD
appcontrol    myapp.openshift.local            appcontrol    8080   edge

5.3 Enable TLS (If Required)

To enable TLS termination, create a secure Route:

oc create route edge appcontrol --service=appcontrol --hostname=MY_APPCONTROL_DOMAIN

This ensures HTTPS is enforced at the OpenShift Router level.

6. Checking Deployment Status

6.1 Verify Helm Charts

helm ls -n Appcontrol
helm status appcontrol

6.2 Verify Running Pods

oc get pods -l 'app.kubernetes.io/instance in (appcontrol-services,appcontrol)' -n Appcontrol

6.3 Verify AppControl Accessibility

Open your browser and navigate to:

https://MY_APPCONTROL_DOMAIN