This section provides information on how to configure the WhereScape CICD Enablement Pack on both Developer and Deployment Machines.

Prerequisites

The following technologies should be in place before following the configuration setup for all Development and Deployment machines:

Software

• Python 3.11.5
  The following Python libraries have been installed using pip:
  • GitPython - pip install GitPython
  • Tkinter - pip install tk
  • Psycopg2 - pip install Psycopg2
  • PyYAML - pip install PyYAML
  • XML.etree.ElementTree - pip install ElementTree
  • Requests - pip install Requests
  • Logging - pip install Logging
• WhereScape 3D, 9.0.5.4+
  • Instructions on installation can be found at the following link:  WhereScape 3D Installation Instructions.
  • Includes the WhereScape MetaServer (wsmetaserver) which installs a local PostgreSQL database server used to store metadata.
  • This PostgreSQL server is typically installed automatically during the WhereScape 3D setup process.
  • Alternatively, users can connect to an existing PostgreSQL server if preferred.
• WhereScape RED, 10.4.0.1+
  • Requires a PostgreSQL database to store metadata. 
  • This can be hosted on the same MetaServer (wsmetaserver) installed with WhereScape 3D or on a separate PostgreSQL server, depending on your environment setup
• GIT
  • Repository – this must be created separately. Instructions to do this can be found in the GitHub Documentation here: Creating a GitHub Repository.
  • Supported GIT Platforms:
    • GitHub
    • GitHub Enterprise
    • Azure DevOps
• GIT Tools
  • GIT CMD: can be installed here: GIT CMD Install

Environment Configuration

Ensure that the system-wide PATH environment variable includes the path to the GIT CMD executable (e.g. "C:\Program Files\Git\cmd"):

Make sure the following user-level PATH entries exist: 

• %USERPROFILE%\AppData\Local\Programs\Python\Python311\ 
• %USERPROFILE%\AppData\Local\Programs\Python\Python311\Scripts\ 
• C:\Program Files\Git\cmd\ 
• C:\Program Files\Git\bin\ 

You may need to add Proxy authentication, to enable access to the API for Personal Access token authentication: 

• Add http_proxy: http://[ProxyAddress]:[Proxy Port]
• Add https_proxy: https://[ProxyAddress]:[Proxy Port] 

Installing the WhereScape CICD Enablement Pack

1. Locate the WhereScape CICD Enablement Pack MSI file. 
2. Double-click the .msi file to launch the installer. 
3. Follow the on-screen instructions to complete the installation. 
4. Once installed, a shortcut to the Enablement Pack should appear on your desktop: 
   • Shortcut name: WhereScape CICD Enablement Pack 
   • Location:  %ProgramFiles%\WhereScape\GIT Enablement Pack 

Developer Machine Configuration

This section describes how the workflow should be configured on the Development machine.

Machine Configuration

All developer machines must have the same configuration and installation steps in the Prerequisite section. These processes have been deployed and tested on the following Development machine types: 

• Microsoft Virtual Machines 
• Citrix Machines 
• Desktop machines 

WhereScape 3D and RED - Additional Installation Steps

Downloads for the latest versions of WhereScape 3D & RED, along with installation guides, can be found here: https://www1.wherescape.com/support/software-downloads-documentation/ 

WhereScape 3D and RED Repository (PostgresSQL)

With WhereScape 3D and RED, the metadata is stored in a repository within a PostgreSQL database. The installation process will check and update the PostgreSQL database structure, ensuring that the structure matches the software update requirements. 

WhereScape RED Only

Ensure that the Azkaban service has been installed and started. This can be found in the services of the Virtual Machine.

WhereScape RED Repository Connection Details

Server:        User-specified 

Port:        User-specified 

Database:    wsred_[Name of GIT repository][_$ENVIRONMENT$]_$DEVELOPER$ 

Username:    User-specified 

Password:    User-specified 

GIT Repository Settings

Each end user will require access to the shared GIT repository. The end user’s credentials are used when pushing commits (during the WhereScape 3D & RED workflows). 

Repository Name:    User-supplied 

Repository local path:    %USERPROFILE%\Git\[Name of Repo] 

Deployment Machine Configuration

This section describes how to setup a deployment machine that can be used to create a CICD workflow to publish changes into a selected target database.

This enablement pack will trigger the WST deployment process via the command line. For further information on this, please refer to the WhereScape RED help guide.

Machine Configuration

All deployment machines must have the same configuration and installation steps in the prerequisites section.

Configure Target Environment Runners

To deploy the application to target environments, the below link provides instructions to configure a self-hosted runner as a service. 

For more information consult the documentation here: GitHub - Hosting your Own Runners 

Consideration when Setting up Agents/Runners

It is recommended that you consider this before continuing or selecting the option.

Option1: Create a runner per deployment machine

This will enable the machine to be configured specifically for that runner and the required deployment tasks. For example, you may require specific software for that runner. 

However, this will create a more complex environment to support and may also be more cost-inefficient. 

Option 2: You can create many runners within one deployment machine

This will enable the runners to utilize the setup of the deployment machine environment configuration for many runners. 

When creating the agents or runners, include the solution name within the name of the runner, for example: [Machine Name]_[Project]_[Environment] 

Your selected option depends on how complex you wish to make the environment. Having one deployment machine with many runners may be simpler to support and more cost-effective in the long run. However, this may create an environmental configuration restriction that may prevent you from scaling the solution in the future. 

Also, you should understand the CPU requirements for deployment, as the deployment machine will use the CPU while executing the deployment to the target platform. This is only a consideration if you have many runners on a single deployment machine and, therefore, parallel tasks taking place that are trying to consume the CPU from that deployment machine. 

Workflow Logs

When you run the WhereScape CICD Enablement Pack all workflow logs will automatically be created within the following folder: 

%USERPROFILE%\WhereScape\GIT\Logs 

Whenever you run a workflow task, the user can access these logs to see information relating to them. 

WhereScape 3d, RED & GIT Naming Convention

When you create a repository in WhereScape 3D or RED, its name is automatically linked to the name of your GIT repository.  

Don’t create new repositories in WhereScape 3D that point to existing ones already set up for CI/CD. 

Firewall Rules and Proxy Configuration

1. Your Git Repository. This can include dev.azure.com, github.com 
2. GitHub API: api.github.com 
   1. For Git Enterprise users: https://[url]/api/v3/user/repos 

Next: 

Getting Started with WhereScape CICD Enablement Pack