This documentation supports the 20.08 version of BMC Helix Platform. 
To view an earlier version, select 20.02 from the Product version menu.

Setting up a local Developer Sandbox 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. 

Important

  • The bash scripts enables you to only create a new local development environment. 
  • Upgrading the local development environment is not supported.

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:

Products and installersVersion
PostgreSQL9.5
Microsoft Windows10
Docker

Latest

Important: Make sure you allocate a minimum of 2 CPU and 8 GB RAM for docker.

Git BashLatest
20.08
Latest

The bash scripts enables you to only create a new local development environment. 

Make sure you download and copy the scripts in the sdk folder.

Supported Docker images

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

Docker imageDescription
innovation-suite-bundles-xx.yy.tar

Docker image containing the BMC Helix Platform bundles.

innovation-suite-db-xx.yy.tarDocker image containing the database installation.
innovation-suite-fs-xx.yy.tarDocker image containing the server.

Warning

The docker image provides only BMC Helix Platform bundles. BMC Helix Chatbot and BMC Helix Business Workflows bundles are not provided in the docker image. 

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.

Important

To install and configure docker for MAC OS and Cent OS, see the instructions in notes mac osx.md and notes centos.md files in the scripts folder.

To install PostgreSQL for Microsoft Windows

  1. Download and run  PostgreSQL Database .
  2. Choose the following values during the installation:

    Installation optionsValues
    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.

    Passwordpostgres

    Important: If you choose a different password, you will need to later alter the value of PG_ADMIN_PASSWORD in the script env.sh file.

    Port5432
    Data directory<data-directory>/postgresql-9.5

    Important: 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.

Important

To install and configure docker for MAC OS and Cent OS, see the instructions in notes mac osx.md and notes centos.md files in the scripts folder.

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.

Important

To install and configure docker for MAC OS and Cent OS, see the instructions in notes mac osx.md and notes centos.md files in the scripts folder.

To download and install the scripts

Important

Before you download the script, make sure you download BMC Helix Platform SDK and extract the sdk folder to a desired location (for example, C:\sdk).

  1. Log in to  BMC Developer Portal .
  2. Select BMC Helix Platform > Develop > Request/Manage Sandbox and request for a local developer sandbox.

    After you request is approved, you will receive a notification with the details.
  3. Access and download the scripts for local developer sandbox. 
  4. 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:

    FolderFolder path in Microsoft WindowsFolder Path in Git BashFiles 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-imagesC:\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.

Important

The details for each parameter is provided in the env.sh.template file. The values for the options are already set by default. You only need to uncomment or set options if you want to customize the values.

  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.

Important

To install and configure docker for MAC OS and Cent OS, see the instructions in notes mac osx.md and notes centos.md files in the scripts folder.

Start or stop BMC Helix Platform server

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

./start-server.sh

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

./stop-server.sh

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.

# This parameter is internal to tell if the server starts in install or runtime mode.
# The value should be set to true in install mode and false in runtime mode.
# This value is usually set automatically.
#STANDALONE_SERVER=true

Related topics

Setting up your IDE and installing BMC Helix Platform SDK

Developing and deploying code-based applications

Was this page helpful? Yes No Submitting... Thank you

Comments