OpenShift on-prem deployment guide

This directory describes how to deploy the application to a Red Hat OpenShift cluster you own and operate. It is the on-prem counterpart to the offline-tarball deploy; the same application ships in both forms, with OpenShift getting first-class container-orchestration support via a Helm chart.

Audience

This guide is written for the customer side of an on-prem deployment — typically a platform engineer, OpenShift administrator, or DevOps team responsible for running cluster workloads. It assumes familiarity with oc / kubectl, Helm, OpenShift Routes, and the customer's own conventions for secrets, storage classes, and image registries.

If you are evaluating the software (rather than rolling it into production), see two-modes.md for the Bundled Evaluation install — a single helm install produces a working stack with zero external dependencies.

What's in this directory

File Purpose
index.md This file — orientation and document map
architecture.md What the chart deploys and how the pieces fit together
two-modes.md Bundled Evaluation vs Production install — when to choose which, and what each gives you
deploy.md Step-by-step install procedure
sso.md SAML 2.0 single sign-on — per-org configuration, IdP wiring (Entra ID / Okta / Keycloak / ADFS), attribute mapping, troubleshooting
upgrade.md Upgrade procedure, migration semantics, rollback
troubleshooting.md Common failure modes and how to diagnose them
sandbox-gotchas.md Internal-only — Red Hat Developer Sandbox-specific behaviors that don't apply to customer-managed OpenShift; captured so validation runs are faster

Deployment lifecycle

A typical customer engagement runs end-to-end like this:

  1. Procurement and licensing. Customer signs the master agreement and receives a license file plus an image-pull credential (or the image is mirrored to the customer's internal registry, depending on their policy).

  2. Sizing and prerequisites. The customer's platform team confirms the target OpenShift project, storage class, networking posture (egress, ingress, TLS termination), and decides between the Bundled Evaluation and Production modes documented in two-modes.md.

  3. Pre-install. The customer pre-creates the resources the chart does not own — typically the namespace, image-pull secret, license secret, and (for Production mode) the postgres / redis endpoints plus their credential secrets. See deploy.md §2.

  4. Install. A single helm install against the prepared values file. The chart runs a database-migration Job, then rolls out the application Deployment behind a Service and Route. deploy.md §3.

  5. Verification. Customer hits /health through the Route, signs in as the bootstrap admin, completes first-run setup (admin email, password, terms acceptance), and uploads the license file. See deploy.md §4.

  6. Operate. Routine activity — user provisioning, license assignments, content workflows — all happen through the running application's UI. License assignment can be admin-driven (the default) or user-driven via the optional self-service checkout flow; both modes share a 14-day minimum-hold floor on every assignment to prevent the soft-named-user model from drifting into a floating-license pattern. See deploy.md §6.

  7. Upgrade. Periodic helm upgrade to a newer chart version pulls a newer image and runs any new migrations. upgrade.md.

Compatibility

The chart targets:

  • OpenShift 4.12+ under the default restricted-v2 SecurityContextConstraints. The application image runs with an arbitrary UID assigned by the cluster — no special SCC is required and no cluster-admin grant is needed for install.
  • Vanilla Kubernetes 1.27+ with a working Ingress controller (DOKS, EKS, AKS, etc.) when platform: kubernetes is set in values.

Getting help

A diagnostic-bundle script (oc adm must-gather plus chart values plus sanitized application logs) accompanies each release; running it and attaching the output to a support ticket is the fastest path to resolution. See troubleshooting.md for what to collect when filing.