Setting up a local development environment

As a developer, you can install a BMC Helix Innovation Studio 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 Innovation Studio Developer Sandbox on a local system

Setting up a BMC Helix Innovation Studio 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. Currently, the Developer Sandbox has the following limitations for security purposes:

• No outbound connections are allowed and you cannot perform the following actions:
  • Leverage Web APIs and external record definitions
  • Create custom Java REST API, HTTP, or web service call from the Java code
  • Send and receive emails
• Most of the inbound connections are blocked. Developers cannot connect with the Java IDE to the developer instance and 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 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.

System requirements

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

To install and configure Docker for Microsoft Windows

1. Download and install the lastest version of Docker for Microsoft Windows.

2. Right-click the Docker icon in the system tray.
3. To configure the Docker settings, perform the following steps: 
   For more information, see Get started with Docker for Windows in the docker documentation.

   1. Make sure that a minimum of 2 CPUs is selected and a minimum of 16 GB memory is allocated.

      Best practice

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

      Depending on the version of Docker, to configure CPUs and memory, select Settings > Resources > Advanced. For the latest releases, the configurations are set in the .wslconfig file. For more information, see Docker documentation.

   2. Select Settings > General and select Use the WSL 2 based engine.

   3. Access the wsl.conf file itself from \\wsl$\docker-desktop\etc\ location and check for the following line:

      options="metadata"

      The content in the wsl.conf file should look like the following script:

      [automount]
      root = /mnt/host
      crossDistro = true
      options = "metadata"
   4. 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 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 in 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 and request access to the scripts for local developer sandbox.

2. Select BMC Helix Innovation Suite > Develop > Request/Manage Sandbox.
3. To request for a local developer sandbox, from Your Local Developer Sandbox tab, click REQUEST NOW.
   After you request is approved, download the Local Developer Sandbox files from BMC Developer Portal.

1. Download the sandbox-scripts.zip file and different *.tar.gz docker image files (for example, db.tar.gz, arserver.tar.gz, midtier.tar.gz). 

1. Extract the sandbox-scripts.zip file in a sandbox folder. Move the docker images to the same folder.
   For example, you can extract the file to C:\Sandbox or C:\Users\<userid>\Sandbox folder. 

   The following table displays the structure of the sandbox folder after running the setup_sandbox.sh script:

   Folder	Folder path in Microsoft Windows	Folder Path in Git Bash	Files added to the folder
   logs	C:\sandbox\	/c/sandbox/	Main folder containing the installation scripts.

To create a development environment

Port 5432 must be available for the PostgreSQL container in the sandbox. If the 5432 port is in use, you can change the port in the sandbox.yml file, located in the folder where the setup-sandbox.sh script file exists. 

Also, make sure that ports 8080 and 8008 are available for the server HTTP ports.

Run the script setup-sandbox.sh file by using the following command in Git Bash:

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

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

• Creates the following subfolders:

  Subfolder	Files added to the folder
  logs/	Sandbox setup logs
  logs/ars	AR System server logs
  logs/midtier	Mid Tier logs
  postgres/data	Database storage files.  Important: The size of database storage can grow over 4GB.
  docker-images/	The downloaded docker images are moved to this folder.

• Cleans the database and logs if the script was already executed 
• Loads the Docker images
• Starts the PostgreSQL database as a container using the current official PostgreSQL Docker image
• Restores a base database by using the docker image: innovation-suite-db-xx.xx.tar
• Launches the server by using the docker images: arserver:xxxxxx and midtier:xxxxxx

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

Start or stop BMC Helix Innovation Studio server

To start the server, run the script start-sandbox.sh file by using the following command in Git Bash:

To stop the server, run the script stop-sandbox.sh file by using the following command in Git Bash:

Related topics

Setting-up-your-IDE-and-installing-BMC-Helix-Innovation-Studio-SDK

Developing-and-deploying-code-based-applications