Introduction

Introducing the Next Chapter in FNCM on Container or FileNet Standalone Series!

In this post, we’re zooming in on how to use the FNCM Standalone prerequisite scripts specifically for OpenShift (OCP) deployments.

Getting started with FNCM Standalone prerequisites scripts doesn’t have to be complicated—whether you’re exploring FNCM Standalone for the first time or looking to streamline your deployment process—this guide breaks the process down into clear, actionable steps.

This blog will cover the following topics and features:

1. Running FNCM Standalone prerequisites in gather mode: Gathering deployment details

2. Running FNCM Standalone prerequisites in generate mode: Generating SQL scripts, secrets and CR

3. Running FNCM Standalone prerequisites in validate mode: Validating storage-classes, databases, LDAP, IDP and SCIM

Silent Installation

For silent installation you can use the --silent flag and run the following command:

python3 prerequisites.py --silent gather

Before executing the script in silent mode, ensure that you’ve completed the required fields in the container-samples/scripts/silent_config/silent_install_prerequisites.toml file. This file contains helpful comments and default values to guide you in entering the correct information.

For instance, the following section defines the FNCM Operator version. By default, the value is set to 5 corresponding to version 5.7.0:

# ####################################################
# ##     Filenet Content Manager Version            ##
# ####################################################
# Filenet Content Manager version to be deployed - Valid values: [1; 2; 3; 4; 5]
# 1. 5.5.8
# 2. 5.5.11
# 3. 5.5.12
# 4. 5.6.0
# 5. 5.7.0
FNCM_VERSION = 5

Once the script completes gather mode execution, it will generate the necessary property files. You can review the structure of these generated files in the summary output at the end of the gather process.

Move Feature of Gather Mode

If you are moving from an on-premises installation to a container-based deployment, you can run the --move flag with the gather mode to pre-fill the property files using your existing configurations.

When an on-prem environment is set up, the Content Manager User Interface (CMUI) creates a CPE configuration manager profile that stores the configuration data in XML files.

 The script accepts the following files:

• configurejdbcecm.xml​
• configureldap.xml​
• configurejdbcgcd.xml
• configurejdbcos.xml

You can provide either:

• The entire Configuration Manager profile folder, or

• A subset of files, depending on what configurations you'd like to reuse (e.g., only LDAP or DB files).

To exclude specific configurations, simply remove the corresponding file from the folder. You can also supply multiple XML files for Object Stores or LDAP, named as configurejdbcos.2.xml, configureldap.2.xml, etc.

The script parses the supplied XML files and pre-fills the .toml property files with necessary values.

Note: For security reasons, passwords are not extracted from the configuration manager files and always need to be reentered.

 You can use these files to run the gather mode with move feature with the following command:

python3 prerequisites.py gather --move <PathToFolder>

Replace <PathToFolder> with the path to your Configuration Manager profile folder as shown in the example: 

Editing the Property Files

When you run the prerequisites in gather mode, it generates a set of property files. These files are essential for the generate mode, which uses the values provided in them to create the necessary configuration files for your deployment.

The generated property .toml files are saved inside the following directory:

../container-samples/scripts/propertyFile

You must edit these files before proceeding to generate mode by filling in all the <Required> placeholders. By default, the following files will be created:

• fncm_components_options.toml

• fncm_db_server.toml

• fncm_deployment.toml

• fncm_user_group.toml

Additional files will be created based on the authentication type you selected:

• fncm_ldap_server.toml

• fncm_identity_provider.toml

• fncm_scim_server.toml

Each .toml file generated in gather mode serves a specific purpose and contains configuration parameters that must be filled before you proceed with generate mode:

• fncm_deployment.toml : Contains general deployment settings such as the FNCM version, components to be installed, and storage class names.

• fncm_components_options.toml Holds details about optional components. This includes configuration for Java SendMail, Task Manager custom users and groups, and other component-specific settings.

• fncm_db_server.toml Defines database connection details for each database used in the deployment. Each database (e.g., GCD DB, ICN DB, and object store DBs) is identified by a unique ID.

• fncm_user_group.toml Specifies application login credentials for P8 CPE and ICN, keystore and LTPA passwords, and user/group assignments needed for configuring access and roles.

• fncm_ldap_server.toml Captures LDAP configuration including server URLs, credentials, base DNs, and SSL settings if applicable. Each LDAP is identified by a unique ID.

• fncm_identity_provider.toml Contains IdP configuration details such as discovery endpoint, credentials, and token-related settings. Each IDP is identified by a unique ID.

• fncm_scim_server.toml Stores SCIM server details including server URLs, context paths, SCIM client credentials, and token URL.

Each file includes helpful comments and templates for helping you enter the information without errors. For instance, the template to enter the database server name is given below:

# Provide the database server name or IP address of the database server. If using IPv6, enclose the address in square brackets ([...])
DATABASE_SERVERNAME = "<Required>"

In this case, replace <Required> with your actual database server name.

Alongside the .toml files, there will be another folder ssl-certs. This folder will contain subdirectories for each component that may require SSL certificates:

• gcd - GCD database

• icn - IBM Content Navigator database

• os - Object Store databases

• ldap - LDAP servers

• idp - Identity Providers

• scim - SCIM servers

If SSL is enabled for any of these services, place the required certificates in the corresponding sub-folder. Additionally, if you are connecting to any external services over SSL, you can place their certificates in: propertyFile/ssl-certs/trusted-certs. 

The script supports certificate chaining as well as bundling of multiple peer certificates into a single file.

For certificate chaining, you can place a root certificate, any intermediate certificates, and the leaf certificate in the designated folder. The script will automatically combine them into a properly ordered certificate chain file, ensuring compatibility with TLS configurations that require full chain validation.

Additionally, for scenarios like DB2 HADR deployment, you can place the primary and secondary node certificates in the same folder. The script will merge them into a single bundle and generate the appropriate template for secret creation.

Make sure all required information is completed in the .toml files and the appropriate certificates are in place before proceeding to generate mode.

If you have enabled IBM Content Collector P8 support for IBM Content Search Services, you must create a secret to hold the encryption key information from IBM Content Collector.

This secret must be placed inside the icc subfolder located within the propertyFile directory.

For detailed instructions on creating the secret, see: Creating Secret Hold Encryption Key Information from Content Collector.

Generated Files

The SQL templates for creating the databases will be generated in the database subfolder inside the generatedFiles directory. These are templates and should be reviewed and updated as needed before use.

For secrets, YAML templates containing configuration data such as login credentials will be created in the secret subfolder. Secrets containing SSL certificates will be placed in the SSL subfolder.

Additionally, the generatedFiles directory includes the Custom Resource (CR) YAML file of kind FNCMCluster. This CR file holds all the required configuration data that the operator will use to create the FNCMS deployment.

You can review the generated files, and use the SQL templates to create the databases.

Running FNCM Standalone prerequisites in validate mode

Running the prerequisites script in validate mode performs a round of sanity checks on the prerequisites—such as the storage classes, databases, and authentication mechanisms (LDAP/IDP/SCIM)—and also helps to create the necessary secrets and apply the generated CR file to your deployment.

You can run the prerequisites in validate mode with the following command:

python3 prerequisites.py validate

Notes: Before executing the prerequisites script in validate mode,

• • Ensure you are logged into the cluster and are using the correct project by running the oc project command.

  • Make sure you have created all the databases using the previously generated SQL templates.

The logic in validate mode closely mirrors with that of the operator. It helps to catch configuration issues early before initiating the deployment. You can also run the validation directly from the operator pod. All the required dependencies are pre-installed. You can copy the script files and run the validation in the operator by using the following steps:

cd container-samples
export OPERATOR=$(kubectl get pods -l 'name=ibm-fncm-operator' | awk 'NR>1 {print $1}')
kubectl cp scripts  $OPERATOR:/opt/ansible
kubectl exec -it $OPERATOR -- bash
cd /opt/ansible/scripts
python3 prerequisites.py validate

The script also displays this usage information automatically at the beginning of the validate mode, along with the script version and execution mode, as shown below:

• The script begins by creating a truststore to hold all required SSL certificates.
  

  

• It first validates storage classes:

  • Checks if the specified StorageClass exists

  • Creates a sample PVC with the specified StorageClass (default size=1GB)

  • Checks the liveness of the created PVC

  • Waits for the PVC to reach the Bound state, confirming that the provisioner is functioning.

  • Verifies whether the bound volume supports the ReadWriteMany (RWX) access mode.

    

  • You can specify the custom size of PVC to be created by using the --pvc-size or -pvc flag. For example:

    python3 prerequisites.py validate -pvc 2Gi

    Note: The PVC size needs to be specified in either Mi or Gi.

  • To exclude the storage classes validation, run the command with -sc or --skip-storageclass flag:

    python3 prerequisites.py validate -sc 
    

• Next, the script proceeds to validate the database connections:

  • Checks server reachability
    • The script ensures that the database server is reachable over the network.
    • This helps to catch common issues like:
      • DNS resolution failures
      • Incorrect hostnames 
      • Firewall blocks
    • If SSL is enabled:
      • A SSL context is created using the given server certificate.
      • A secure socket is created.
      • Attempts to connect to the database server.
      • Validates the TLS protocol version in use
        

        Note: Only TLSv1.2 and TLSv1.3 are supported. Validation will fail for any other protocol version.

      • Checks and displays the supported cipher suite negotiated during the SSL handshake
    • If you are using non-SSL (not recommended):
      • The script attempts a plain TCP connection.
      • A plain TCP socket is created.
      • Attempts a direct socket connection to the server.
    • If reachability over SSL is failed, the script will fall back to non-SSL connection.

  • Imports the supplied certificate into the truststore

  • Attempts to connect to at least one IP address associated with the server

  • Authenticates the connection
    • If SSL is enabled, the script performs additional validations:
      • Imports the supplied certificate into the created local truststore
      • Performs an SSL authentication using the imported certificate

  • Finally the script measures and displays the latency of the connection  and checks whether it falls within the accepted range. If the latency exceeds the accepted range, it is highlighted in red, indicating a potential performance issue or network instability that could impact database operations.
    

    

    
    

  • This is repeated for all the databases in the fncm_db_server.toml file.

  • To exclude the database validation, run the command with -db or --skip-database flag:

    python3 prerequisites.py validate -db
    

• If LDAP is configured:

  • Verifies the LDAP server reachability.

    • This is similar to database server reachability check discussed above. (See: Checks server reachability)

  • Once the connected, the script measures the connection latency

    • If the latency is within acceptable limits, it is logged as healthy.

    • If the latency exceeds the defined threshold, it is highlighted in red, signaling potential network performance issues or connectivity problems.

  • Binding to the LDAP server
    • The script attempts to bind to the LDAP server using the provided Distinguished Name (DN) and credentials.
    • If SSL enabled:
      • The supplied certificate is imported into the truststore.
      • The connection is then established over SSL.
      • The script attempts to bind using the imported certificate and the credentials.

  • Validates Users and Groups.

    • Once bound, the script performs a user and group validation check.

    • It queries the LDAP directory for the expected entries.

    • The results are displayed:

      • Valid entries are marked as found.

      • Missing users or groups are clearly indicated as "Not Found", helping to quickly identify configuration issues in the property file.
        
        

        

        
        

  • To exclude the LDAP validation, run the command with -l or --skip-ldap flag:

    python3 prerequisites.py validate -l
    

• If IDP is configured:

  • Validates the IDP server reachability
    • This is similar to database server reachability check discussed above. (See: Checks server reachability)

  • Attempts to retrieve an ID token from the configured IDP using the token URL and credentials.

  • Decodes the token using JWKS and validates its claims based on the configurations in fncm_identity_provider.toml.

  • The behavior differs based on the IDP configuration:

    • For LDAP-based IDPs, token retrieval is best-effort — if the token cannot be retrieved (e.g., password or client credentials grant is not supported), the validation does not fail, since IBM Liberty uses browser-based login through user interaction (OAuth authorization code flow)

      

    • For SCIM-based IDPs, token retrieval is mandatory. Both password grant and client credentials grant must be supported. If either fails, the validation will fail.

      

  • To exclude the IDP validation, run the command with -idp or --skip-idp flag:

    python3 prerequisites.py validate -idp
    

• If SCIM is configured:

  • Verifies the SCIM server reachability.
    

    • This is similar to database server reachability check discussed above. (See: Checks server reachability)

  • An access token is requested using the client credentials grant via the configured IDP.

    • This is an authentication where the client ID and secret is used directly to obtain a JWT (JSON Web Token).

      

  • Decodes the token using the JWKS Endpoint

    • Once the token is retrieved, it is decoded and validated using the IDP's JWKS (JSON Web Key Set) endpoint exposed by the IDP. 
    • The JWKS URI is discovered automatically via the IDP’s Discovery Endpoint.
    • This ensures the token is authentic, not expired and contains all the required claims and attributes configured.
  • Validates SCIM Mapping Attributes
    • The script then inspects specific SCIM-related attribute mappings defined in the IDP configuration:

      • USER_IDENTIFIER: Common user ID (e.g., username or email)

      • UNIQUE_USER_IDENTIFIER: A globally unique identifier used for cross-system identity mapping

      • USER_IDENTIFIER_TO_CREATE_SUBJECT: Used when creating user records (subjects).
        

        Note: The script uses the UNIQUE_USER_IDENTIFIER for SCIM queries — not USER_IDENTIFIER.This approach ensures reliable users and groups resolution across different IDPs and environments, where USER_IDENTIFIER may not be consistent.

• • • Uses the access token to query users and groups from the SCIM server. This helps to validate whether the IDP-SCIM integration is returning accurate data.

  • Validates the retrieved users and groups against the entries in the fncm_scim_server.toml.

    • Validates FileNet Admin User

      

    • Validates Navigator Admin User

      

    • Validates the Admin Group

      

    • Validates Non-Admin Users and Groups

      

  • To exclude the SCIM validation, run the command with -scim or --skip-scim flag:

    python3 prerequisites.py validate -scim
    

If any prerequisite check fails, the script will display an error message in the terminal, as shown below:

The script also displays information about what went wrong, relevant error details and debugging suggestions to help you resolve the issue. An example of a certificate issue is shown below:

If you encounter any errors:

• You should review and edit the property files and certificates to correct the configuration. 
• Once changes are made, re-run the script in generate mode to re-generate your template files.
• Then, execute the validate mode again to confirm that all settings are correctly applied and the system is ready for use.

If all the validations are successful, the script displays a All prerequisites are validated message as below:

Then the script asks if you want to apply the generated secret templates in your deployment. If you select yes, all the generated secrets—such as credentials and SSL-related secrets—will be applied:

Finally, the script prompts you to apply the generated Custom Resource (CR) YAML file to initiate the deployment process.

Tips

1. You can run the script with the --help flag to view all the different modes and usage options:

   python3 prerequisites.py --help
   

2. To get additional logs into the command line as you execute the scripts, you can enable verbose mode. For instance, to get additional information while validating the prerequisites, run the following command:

   python3 prerequisites.py --verbose validate
   

3. To get the details on a specific MODE, you can use the --help flag. For instance, to get the different usage options of validate mode, you can run the following command:
   

   python3 prerequisites.py validate --help

4. All the execution logs will be stored in the file: container-samples/scripts/prerequisites.log. You can refer to this log to debug issues or review script activity.

If you have any questions or run into issues, feel free to reach out to the FileNet Standalone community on GitHub:  https://github.com/ibm-ecm/container-samples—we're here to help!

Thanks for reading!
Stay tuned for our next post.

Happy deploying!