Setting up a local development environment

As a developer, you can install a BMC Helix Platform Developer Sandbox on your local system by running a docker container. You can use this local Developer Sandbox to develop and test your applications on your machine without the same security restrictions placed on the Amazon Web Services (AWS) Developer Sandbox instances on BMC Developer Portal. To create a local development environment, use the scripts provided by BMC. 

Benefits of running a BMC Helix Platform Developer Sandbox on a local system

Setting up a BMC Helix Platform Developer Sandbox on your local system provides the following benefits:

• Full testing and debugging capability
• Capability to build and leverage Web APIs and external record definitions
• Support for incoming REST API calls
• Ability to send and receive emails
• Share folders between the laptop and the docker instance to have the logs available locally

Limitations of accessing Developer Sandbox on BMC Developer Portal

The Developer Sandbox instances provided by BMC are currently running on AWS instances and therefore have the following limitations for security purposes:

• No outbound connections allowed preventing the following features from working:
  • Leveraging Web APIs and external record definitions
  • Creating custom Java REST API, HTTP, or web services call from the Java code
  • Sending and receiving emails
• Most of the inbound connections are blocked preventing the developer from connecting the Java IDE to the developer instance to debug the Java code.
• The debug port is closed, preventing the developers from testing and debugging their custom Java code. 
• No support for deploying bundles that are not built by the developer in the Developer Sandboxes, preventing developers from building custom extensions for other applications, such as the applications developed by BMC. 
• Blocked connection to the docker instance preventing the developer from freely accessing the logs.
• No ability to code locally and deploy the custom code in the cloud. 

System requirements

The following table lists the operating system and installers you need to set up the local development environment:

Supported Docker images

Make sure that you download the following docker images in the /scripts/docker-images folder:

To install and configure Docker for Microsoft Windows

1. Download and install Docker version 2.3.0.3 or later for Microsoft Windows.

2. Right-click on Docker icon in the System Tray.
3. Configure Docker settings. 
   For more information, see Get started with Docker for Windows in the docker documentation.

   1. Select Settings > Resources > Advanced and ensure that a minimum of 2 CPUs is selected and minimum of 6 GB memory is allocated.

      Best practice

      To configure the docker image, we recommend that you allocate 8 GB memory.

   2. Select Settings > Resources > File Sharing and configure the drive where you have installed the scripts. For example, the C or the D drive.

To install PostgreSQL for Microsoft Windows

1. Download and run PostgreSQL Database.

2. Choose the following values during the installation:

   Installation options	Values
   Installation directory	<tools-directory>/postgresql-9.5 Important: The <tools-directory> folder contains the necessary binaries for the third-party tools, such as Git Bash, PostgreSQL.
   Password	postgresImportant: If you choose a different password, you will need to later alter the value of PG_ADMIN_PASSWORD in the script env.sh file.
   Port	5432
   Data directory	<data-directory>/postgresql-9.5Important: The <data-directory> folder contains the necessary data for the third-party tools, such as Git Bash, PostgreSQL.

3. Overwrite your <data-directory>/postgresql-9.5/pg_hba.conf file with pg_hba.conf file.
   If you do not want to overwrite the file, make sure you replace the IPv4 and IPv6 local connections with the following updates to change the authentication type to md5:

   # TYPE DATABASE USER ADDRESS METHOD
   # IPv4 local connections:
   host all all 0.0.0.0/0 md5
   # IPv6 local connections:
   host all all ::1/128 md5
   # Allow replication connections from localhost, by a user with the
   # replication privilege.
   #host replication postgres 127.0.0.1/32 md5
   #host replication postgres ::1/128 md5

4. Overwrite your <data-directory>/postgresql-9.5/postgresql.conf file with the postgresql.conf file.
   If you do not want to overwrite the file, make sure you make the following updates in the postgresql.conf file:

   listen_addresses = '*'
   max_connections = 10000
5. Restart the PostgreSQL server.

To install Git Bash

1. Access the Git Download URL, and select Windows.

2. Cancel the download for the default git installer, and from the UI, select the 64-bit Git for Windows Portable option.
3. After you run the executable file, the Git command line program is installed at the C:\git\PortableGit folder.

Git Bash is saved as git-bash.exe inside the PortableGit folder.

To download and install the scripts

1. Log in to BMC Developer Portal.

2. Select BMC Helix Platform > Develop > Request/Manage Sandbox and request for a local developer sandbox.
   
3. After you request is approved, download the Local Developer Sandbox files from BMC Developer Portal.
    

1. Extract the script files under the scripts folder in your sdk folder.
   For example if your SDK folder is located at C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\, copy the script files at C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\scripts\ folder. 

   The following table displays the structure of the scripts folder:

   Folder	Folder path in Microsoft Windows	Folder Path in Git Bash	Files added to the folder
   scripts	C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\scripts\	/c/sdk/com.bmc.arsys.rx.sdk-20.08.00/scripts/	Main folder in the SDK folder containing the scripts.
   utils	C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\scripts\utils	/c/sdk/com.bmc.arsys.rx.sdk-20.08.00/scripts/utils	Folder containing the utility scripts used by the main scripts.
   docker-images	C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\scripts\docker-images\	/c/sdk/com.bmc.arsys.rx.sdk-20.08.00/scripts/docker-images/	Server docker images (server, database utility and bundles).

To configure the environment settings

The env.sh file contains the options applicable for the scripts, for example the Tenant domain name, Tenant name, the path to the postgres psql utility. By using the env.sh file, you do not need to modify any of the scripts, you only have to provide values in this file.

1. Copy the file env.sh.template and rename the copy to env.sh.
2. Edit env.sh to update the values for the following parameters:
   • PATH_POSTGRES_PSQL—path to the PostgreSQL psql utility. 
   • TENANT_DOMAIN_NAME—The tenant domain name. Default value is mycompany.com.
   • TENANT_NAME—The tenant name. Default value is mycompany.

To create a development environment

1. Run the script clean-install-and-start.sh file by using the following command in Git Bash:

   ./clean-install-and-start.sh

   The script performs the initial sanity checks such as checking if the docker is running, enough resources are allocated, and PostgreSQL is available and configured.

2. After performing the initial checks, the script performs the following tasks:
   

   • Creates the following subfolders:

     Folder path in Microsoft Windows	Folder path in Git Bash	Files added to the folder
     C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\scripts\db\	/c/sdk/com.bmc.arsys.rx.sdk-20.08.00/scripts/db/	Server SaaS logs
     C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\scripts\tenant\	/c/sdk/com.bmc.arsys.rx.sdk-20.08.00/scripts/tenant/	Server tenant logs
     C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\scripts\dbbackup\	/c/sdk/com.bmc.arsys.rx.sdk-20.08.00/scripts/dbbackup/	Database installation logs and backup files
     C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\scripts\logs\	/c/sdk/com.bmc.arsys.rx.sdk-20.08.00/scripts/logs/	Script logs
     C:\sdk\com.bmc.arsys.rx.sdk-20.08.00\scripts\backup_env.sh\	/c/sdk/com.bmc.arsys.rx.sdk-20.08.00/scripts/backup_env.sh/	env.sh backup files

   • Cleans the database and logs if the script was already executed 
   • Loads the Docker images
   • Installs the database by using the docker image: innovation-suite-db-xx.xx.tar
   • Launches the server in installation mode by using the docker image: innovation-suite-fs-xx.xx.tar
   • Launches the server in runtime mode by using the docker image~: innovation-suite-fs-xx.xx.tar
   • Deploys the necessary bundles by using the docker image: innovation-suite-bundles-xx.xx.tar
   • Creates the tenant and other necessary accounts

After the installation is complete, a link to BMC Helix Innovation Studio is displayed along with the credentials for SaaS administrator, tenant administrator, and developer.

Start or stop BMC Helix Platform server

Run the following start-server.sh script in Git Bash:

Run the following stop-server.sh script in Git Bash:

Troubleshooting

Reinstalling the development environment by using the same env.sh file

If you reinstall the local development environment by using the same env.sh file, the clean-install-and-start.sh file displays an error to set STANDALONE_SERVER to true.

The STANDALONE_SERVER environment variable indicates if the server runs in the installation mode (true) or runtime mode (false). During installation, the server initially runs in the installation mode to install the workflow. After the installation is complete, the server runs in runtime mode.

The installation scripts automatically changes the value of STANDALONE_SERVER to false at the end of installation.

To resolve this issue, edit your env.sh file, and comment the STANDALONE_SERVER environment variable.

Related topics

Setting-up-your-IDE-and-installing-BMC-Helix-Platform-SDK

Developing-and-deploying-code-based-applications