Installing TSF

Install TSF by starting the installer container, configuring the cluster and integrations, and deploying all services. This phase assumes you have prepared your environment and credentials.

Start the installer container

Start the TSF installer container using Podman. The installer runs in a container image that includes the tsf command-line tool and all required dependencies.

Prerequisites

You have prepared the tsf.env file with your cluster and integration credentials.
You have Podman installed on your local system.

Steps

Navigate to the directory that contains your tsf.env file.
Start the TSF installer container:
```
podman run -it --rm --env-file tsf.env \
  --entrypoint bash -p 8228:8228 --pull always \
  quay.io/redhat-ads/tsf-cli:unstable --login
```
This command pulls the latest installer image and opens an interactive shell session inside the container. The --login flag sources the shell profile, and port 8228 is exposed for the GitHub App creation workflow.
In the container terminal, log in to your OCP cluster:
```
oc login "$OCP__API_ENDPOINT" \
  --username "$OCP__USERNAME" \
  --password "$OCP__PASSWORD"
```
If the cluster uses a self-signed certificate, type y when prompted to use an insecure connection.

Verification

Verify that you are logged in with cluster-admin privileges:

oc whoami

The output shows the username you specified in your environment file.

Configure the cluster

Create the TSF configuration on your OCP cluster. This step creates a ConfigMap that defines which components TSF installs and how they are configured.

Steps

Create the TSF configuration:
```
tsf config --create
```
This command creates a tsf-config ConfigMap in the tsf namespace. The ConfigMap contains a config.yaml key that lists all components with their namespaces and manageSubscription settings.
Check if the Red Hat Cert-Manager Operator is already installed on the cluster:
```
oc get subscription openshift-cert-manager-operator -n cert-manager-operator
```
- If the command returns a subscription, Cert-Manager is already installed. Continue to step 3.
- If the command returns NotFound, Cert-Manager is not installed. Skip to the verification step.
Edit the tsf-config ConfigMap to disable the Cert-Manager managed subscription:
```
oc edit configmap tsf-config -n tsf
```
Locate the Cert-Manager product entry and set manageSubscription to false:
```
products:
  - name: Cert-Manager
    enabled: true
    properties:
      manageSubscription: false
```

The TSF installer assumes a fresh cluster. If other TSF-managed operators are already installed (such as Red Hat OpenShift Pipelines or Red Hat Trusted Artifact Signer), set manageSubscription: false for each pre-installed component to prevent conflicts.

The tsf-config ConfigMap in the tsf namespace controls which components are installed. Each component has an enabled flag and a manageSubscription property. Set manageSubscription to false for any component that is already installed on the cluster.

Verification

Verify that the ConfigMap was created:

oc get configmap tsf-config -n tsf

The output shows the tsf-config ConfigMap in the tsf namespace.

To view the complete ConfigMap structure:

oc get configmap tsf-config -n tsf -o yaml

Configure the GitHub integration

Create and install a GitHub App that enables TSF to interact with your GitHub repositories. The GitHub App provides webhooks for triggering builds and access to repository contents.

Prerequisites

You have started the TSF installer container.
You are logged in to the OCP cluster.
You have created the TSF configuration on the cluster.
You have a GitHub organization.

Steps

Create the GitHub App:

tsf integration github --create --org "$GITHUB__ORG" "<my_github_app_name>"

The command outputs a URL starting with http://localhost:8228.

The installer may log an error about failing to open the browser. This is expected when running inside a container. Copy the localhost:8228 URL from the output and open it manually in your web browser.

Open the URL in a web browser. The page displays a Create your GitHub App button.
Click Create your GitHub App. You are redirected to GitHub to configure the app.
On the GitHub App creation page, review the pre-filled settings and click Create GitHub App.
After the app is created, click Install the GitHub App to install it on your organization.
Select your GitHub organization from the list.
Review the permissions that the app requests:
- Read access to members, metadata, and organization plan
- Read and write access to administration, checks, code, issues, pull requests, and workflows
Click Install.

Verification

The GitHub App page displays with a Website link that points to the Konflux UI. You can use this link to access the UI after deployment is complete.
In the GitHub organization settings under Developer settings > GitHub Apps, the newly created app appears with the correct permissions.

Configure the GitLab integration

If you are using GitLab instead of GitHub, configure the GitLab integration. Create a Project Access Token for each GitLab project that you want to onboard to TSF.

Prerequisites

You have started the TSF installer container.
You are logged in to the OCP cluster.
You have a GitLab project that you want to onboard.

Steps

In your GitLab project, create a Project Access Token:
1. Navigate to Settings > Access Tokens.
2. Enter a name for the token, for example, tsf-integration.
3. Select the Maintainer role.
4. Select the following scopes: api, read_repository, write_repository.
5. Click Create project access token.
6. Copy the token value.
Create a Kubernetes secret in the tenant namespace that contains the GitLab credentials:
```
oc create secret generic gitlab-auth-secret \
  -n <tenant-namespace> \
  --from-literal=password="$GITLAB__TOKEN" \
  --type=kubernetes.io/basic-auth
```
The default tenant namespace is default-tenant. If multiple namespaces are used, the secret must be created in each namespace where you onboard components. For more information about tenant namespaces, see Managing environments in the Konflux documentation.

Label the secret so that Konflux can discover it:

oc label secret gitlab-auth-secret \
  -n <tenant-namespace> \
  appstudio.redhat.com/credentials=scm

Annotate the secret with the GitLab host:

oc annotate secret gitlab-auth-secret \
  -n <tenant-namespace> \
  appstudio.redhat.com/scm.host="$GITLAB__HOST"

Verification

Verify that the secret was created:

oc get secret gitlab-auth-secret -n <tenant-namespace>

Configure the Quay integration

Configure the Quay registry integration so that TSF can push built container images to your Quay organization.

Prerequisites

You have started the TSF installer container.
You are logged in to the OCP cluster.
You have created a Quay OAuth token with access to your Quay organization.

Steps

Configure the Quay integration:

tsf integration quay \
  --organization="$QUAY__ORG" \
  --token="$QUAY__API_TOKEN" \
  --url="$QUAY__URL"

When a new component is onboarded to Konflux, a repository is automatically created in the specified Quay organization. If you are using a free quay.io account, you must manually change the visibility of new repositories to public because of account limitations. If you are using a paid quay.io account, the repositories can remain private.

Verification

Verify that the Quay integration secret was created in the tsf namespace:

oc get secret tsf-quay-integration -n tsf

The output shows the tsf-quay-integration secret of type Opaque.

Deploy TSF

Deploy all TSF services to your OCP cluster. This step installs and configures all components of the software factory using Helm charts.

Prerequisites

You have started the TSF installer container.
You are logged in to your OCP cluster with cluster-admin access.
You have created the TSF configuration on the cluster.
You have configured the GitHub or GitLab integration and the Quay integration.

Steps

Deploy all TSF services:

tsf deploy

The deployment process installs 9 Helm charts sequentially, creating the following OCP projects:

cert-manager-operator
konflux-operator
konflux-ui
openshift-storage
rhbk-operator
rhtpa-operator
tssc-keycloak
tssc-quay
tsf-tas

tsf-tpa

The deployment typically takes about 15 minutes. Some charts may take several minutes without producing output. This is expected behavior. If deployment fails, you can re-run the tsf deploy command. The installer attempts to deploy all charts, including those that previously succeeded.

Monitor the command output. As the deployment progresses, the CLI prints the status of each Helm chart, including:
- Chart name, version, and namespace
- Service URLs for Konflux, Red Hat Trusted Artifact Signer (Fulcio, Rekor, TUF), and Red Hat Trusted Profile Analyzer
Save the deployment output for future reference, particularly the service URLs displayed at the end.

The deployment finishes with:
```
Deployment complete!
```

Next step

Proceed to Verifying and accessing TSF.