This documentation supports the 22.1 version of BMC Helix Innovation Studio.

To view an earlier version, select the version from the Product version menu.

Setting up a local Developer Sandbox 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 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 enable you to only create a new local development environment. 
  • Upgrading the local development environment is not supported.

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 from 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 services 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:

Products and installersVersion
Microsoft Windows11
Docker

Latest

(Minumum version 20.01.xx)

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

Git BashLatest
Latest

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


Warning

The docker image provides only BMC Helix Innovation Suite bundle. BMC Helix Business Workflows bundle is not included in the docker image. 

To install and configure Docker for Microsoft Windows

  1. Download Open link  and install Docker version 20.10 or later 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 Open link  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 Open link .

    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 Open link 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 Open link and request access to the scripts for the 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.
  4. Download the sandbox-scripts.zip file and different *.tar.gz docker image files (for example, db.tar.gz, arserver.tar.gz, midtier.tar.gz).
  5. Extract the sandbox-scripts.zip file into a sandbox folder. Move the image .tar.gz files into 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:

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

./setup_sandbox.sh

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/arsAR 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.

To 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:

./start-sandbox.sh

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

./stop-sandbox.sh

Related topic

Developing and deploying code-based applications

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

Comments