Documentation › On-Premises Installation

On-Premises Installation & Deployment

Admin For teams running MaxTAF Cloud inside their own network — for example to test an internal Maximo without exposing it to the internet.

MaxTAF Cloud is a Kubernetes-native platform of Spring-Boot microservices with an Angular frontend. This guide describes the architecture, prerequisites and topology a self-hosted deployment must provide, so your platform team can plan and stand it up.

Work with Code Development Ltd on a production install

Production images, registry access, licensing and a hardened configuration are provided by Code Development Ltd as part of an on-prem engagement. This page is a reference architecture to plan against — it is not a copy-paste installer. Engage your account manager before deploying to production.

On this page

Architecture
Components
Prerequisites
Topology & namespaces
Configuration & ports
Execution grids
Backup & upgrade
Planning checklist

Architecture at a glance

Internet / intranet
     │
     ▼
  Ingress (TLS)  ─►  Frontend (Angular + nginx)  ─►  Gateway (auth + routing)
                                                        │
        ┌───────────────────────────────────────────────┼───────────────────────────────┐
        ▼               ▼            ▼           ▼        ▼            ▼                   ▼
      cloud          storage     scheduler      ai   user-project  utam-recorder   engine-<project>
   (cases/runs)     (files)     (schedules)  (AI cfg) (users/projs)  (UTAM)        (runs tests; 1/project)
        └───────────────┬───────────────────────────────┘                              │
                        ▼                                                               ▼
                   MariaDB (per-project DBs)                            Selenium grid / Playwright (AI) grid
                        ▲
                   Keycloak (OIDC / SSO)  ◄── Gateway validates JWTs

Requests enter through an ingress with TLS, hit the Angular frontend, and are proxied to the gateway, which authenticates every request and routes it to the right service by path prefix. Tests execute on a per-project engine pod that the platform creates on demand, backed by a browser execution grid.

Components

Component	Role	Path prefix
frontend	Angular SPA served by nginx; proxies API/auth traffic to the gateway.	—
gateway	Single auth chokepoint (OIDC JWT + API-key) and router to all services.	—
cloud	Core: cases, runs, reports, import/export, per-project DB provisioning, Allure.	`/api/maxtaf`
storage	Project file storage (mounts the project volume).	`/api/storage`
scheduler	Scheduled/cron test runs.	`/api/schedule`
user-project	Users, projects, permissions; creates the per-project engine pod at runtime.	`/api/userproject`
ai	AI features and AI-provider configuration.	`/api/ai`
utam-recorder	UTAM route-resolution backend for the recorder.	`/api/utamRecorder`
engine (per project)	Compiles and runs tests (MXML/Java/UTAM); spun up on demand, one per project.	`/api/engine` → `engine-<project>`

Per-project engines

Rather than one shared executor, MaxTAF creates an engine pod per project on demand. This gives each project isolation and its own language servers, but means the platform needs Kubernetes RBAC to create pods and services in its namespace.

Prerequisites

Requirement	Notes
Kubernetes cluster	Vanilla Kubernetes or OpenShift. Must allow the platform service account to create pods/services in its namespace. Some pods run privileged (Docker-in-pod / volume mounts).
Database	MariaDB / MySQL. Each project gets its own database; schema is managed automatically by Liquibase on startup.
Identity provider	Keycloak (with its own database) for OIDC/SSO. The gateway validates JWTs against a MaxTAF realm.
Container registry + pull secret	To host and pull the MaxTAF service images provided by CDL.
Persistent storage	A shared, read-write-many volume for project files (the OpenShift path uses a PVC; a multi-node cluster needs RWX storage rather than node-local hostPath).
Ingress + TLS	An ingress controller and certificate management (e.g. cert-manager) terminating TLS to the frontend.
Browser execution grid	A Selenium grid for scripted/MXML cases, and (for AI cases) the Playwright/AI grid. See Execution grids.

Topology & namespaces

A typical deployment uses separate namespaces to isolate concerns:

Application + database — the microservices and MariaDB, plus the dynamically-created per-project engines.
Identity — Keycloak and its database.
Execution grids — the Selenium grid, and the Playwright/AI grid for AI test cases (and an Appium grid if mobile testing is used).

The platform's environment setting selects the engine image, storage type (hostPath vs PVC), image-pull policy and service account — this is the main knob distinguishing a dev cluster from an OpenShift/production target.

Configuration & ports

Item	Detail
Service ports	Each application service listens on `8080`. The engine additionally exposes language-server and terminal ports.
Database	MariaDB on `3306`; the platform connects as a superuser to create per-project databases.
Auth	Gateway trusts Keycloak-issued JWTs; API-key access uses `X-Maxtaf-Api-Key` + `X-Project-Id` headers (see the REST API).
Frontend proxy	The frontend proxies `/api`, `/keycloak` and terminal traffic to the gateway.
Maximo & execution	Not global config — the Maximo URL and Selenium/AI server are per-project parameters (`mx.maximo.address`, `mx.selenium.server`, `mx.playwright.server`) stored per project and injected into the engine at run time.

Harden secrets before production

The development manifests carry example, hardcoded secrets (database and Keycloak admin credentials). A production install must replace these with proper Kubernetes Secrets / an external secret manager, and scope the platform's RBAC to the minimum required to create per-project engines.

Execution grids

Selenium grid — runs scripted and MXML (Maximo) cases in real Chrome/Firefox/Edge on Linux. Autoscaled node pools serve the common/private pools referenced by mx.selenium.server.
Playwright / AI grid — runs AI test cases: a hub distributes runs to nodes that each drive a browser via a Playwright MCP. Referenced by mx.playwright.server. This grid is a separate component from the core platform and is deployed alongside it.
Appium grid (optional) — for mobile (Android/iOS) execution.

Running these grids inside your network is exactly what lets on-prem MaxTAF reach an internal Maximo without exposing it externally.

Backup & upgrade

Backup — dump all MariaDB databases and snapshot the project files volume on a schedule. MaxTAF ships a backup image/pattern that performs an all-databases dump plus a file-tree archive; replicate it as a CronJob and copy archives off-site.
Project export/import — for moving or restoring an individual project (cases, suites, schedules, files, parameters), use the in-app project export/import. Note runs are not included in a project export — download the runs folder separately if you need run history.
Upgrade — services are independent deployments, so you can roll one at a time. Database schema migrations run automatically via Liquibase when the cloud service starts. Push new images and restart the rollouts (or drive it with GitOps).

Planning checklist

☐ Kubernetes/OpenShift cluster with RBAC for dynamic pod/service creation.
☐ MariaDB (with room for one database per project) + backup plan.
☐ Keycloak + its database, with your SSO/identity source federated.
☐ Container registry loaded with CDL-provided images + pull secret.
☐ RWX persistent storage for project files.
☐ Ingress controller + TLS certificates.
☐ Selenium grid (and Playwright/AI grid if using AI cases; Appium if mobile).
☐ Network path from the grids to your Maximo instance.
☐ Secrets moved out of manifests into a secret manager.
☐ Backup + upgrade runbook agreed with your platform team.

Security & Compliance · REST API · How AI cases execute