Step 8: Start custom apps

SimSpace Weaver doesn't manage the lifecycle of custom apps. You must start your custom apps. It's best practice to start your custom apps before you start your simulation clock, but you can start custom apps after you start the clock.

You can use the CLI helper script to call the StartApp API to start your custom apps.

Important

If you use AWS IAM Identity Center (successor to AWS Single Sign-On) or named profiles for the AWS Command Line Interface (AWS CLI), you must use SimSpace Weaver app SDK version 1.12.1 or higher. The latest version is 1.12.2. For information about SimSpace Weaver versions, see SimSpace Weaver versions. The SimSpace Weaver app SDK scripts use the AWS CLI. If you use IAM Identity Center, you can either copy your IAM Identity Center profile for the AWS CLI to your default profile or provide the name of your IAM Identity Center profile to SimSpace Weaver app SDK scripts with the --profile cli-profile-name parameter. For more information, see Configuring the AWS CLI to use AWS IAM Identity Center (successor to AWS Single Sign-On) in the AWS Command Line Interface User Guide and Named profiles for the AWS CLI in the AWS Command Line Interface User Guide.

Docker

.\weaver-project-name-cli.bat start-app --simulation simulation-name --name app-name --domain domain-name

WSL

Important

We provide these instructions for your convenience. They are for use with Windows Subsystem for Linux (WSL), and are unsupported. For more information, see Set up your local environment for SimSpace Weaver.

./weaver-project-name-cli.sh start-app --simulation simulation-name --name app-name --domain domain-name

The StartApp API call will create and start a new instance of the custom app using the name that you provide. If you provide the name of an app that already exists then you will receive an error. If you want to restart a particular app (instance), you must first stop that app and delete it.

Note

The status of your simulation must be STARTED before you can start custom apps. To check the status of your simulation, see Step 7: Get simulation details.

The sample application provides the ViewApp custom app to view your simulation. This app provides you with a static IP address and port number to connect the simulation clients (you will do this in a later step in this tutorial). You can think of a domain as a class of apps that have the same executable code and launch options. The app name identifies the instance of the app. For more information on SimSpace Weaver concepts, see Key concepts for SimSpace Weaver.

You can use the DescribeApp API to check the status of a custom app after you start it.

Docker

.\weaver-project-name-cli.bat describe-app --simulation simulation-name --app app-name --domain domain-name

WSL

Important

We provide these instructions for your convenience. They are for use with Windows Subsystem for Linux (WSL), and are unsupported. For more information, see Set up your local environment for SimSpace Weaver.

./weaver-project-name-cli.sh describe-app --simulation simulation-name --app app-name --domain domain-name

Docker

To start the view app in this tutorial

1. If you aren't there already, go to the tools folder for your project and platform. Your project-folder is path\project-name using the values that you provided when you created the project.

   At a Windows command prompt, enter:

   cd project-folder\tools\windows

2. Use the CLI helper script to call StartApp for ViewApp.

   .\weaver-project-name-cli.bat start-app --simulation simulation-name --name ViewApp --domain MyViewDomain

3. Call DescribeApp to check the status of your custom app.

   .\weaver-project-name-cli.bat describe-app --simulation simulation-name --app ViewApp --domain MyViewDomain

WSL

Important

We provide these instructions for your convenience. They are for use with Windows Subsystem for Linux (WSL), and are unsupported. For more information, see Set up your local environment for SimSpace Weaver.

To start the view app in this tutorial

1. If you aren't there already, go to the tools folder for your project and platform.Your project-folder is path/project-name using the values that you provided when you created the project.

   At a Linux shell prompt, enter:

   cd project-folder/tools/linux

2. Use the CLI helper script to call StartApp for ViewApp.

   ./weaver-project-name-cli.sh start-app --simulation simulation-name --name ViewApp --domain MyViewDomain

3. Call DescribeApp to check the status of your custom app.

   ./weaver-project-name-cli.sh describe-app --simulation simulation-name --app ViewApp --domain MyViewDomain

After the status of your custom app (instance) is STARTED, the output of DescribeApp will include the IP address and port number for that custom app (instance). In the following example output, the IP address is the value of Address and the port number is the value of Actual in the EndpointInfo block.

{
    "Status": "STARTED",
    "Domain": "MyViewDomain",
    "TargetStatus": "STARTED",
    "Simulation": "MyProjectSimulation_22-10-04_22_10_15",
    "LaunchOverrides": {
        "LaunchCommands": []
    },
    "EndpointInfo": {
        "IngressPortMappings": [
            {
                "Declared": 7000,
                "Actual": 4321
            }
        ],
        "Address": "198.51.100.135"
    },
    "Name": "ViewApp"
}

Note

The value of Declared is the port number that your app code should bind to. The value of Actual is the port number that SimSpace Weaver exposes to clients to connect to your app. SimSpace Weaver maps the Declared port to the Actual port.

Note

You can use the procedure from the quick start tutorial to get the IP address and port number of any started custom app, independent of this workflow.