AWS Mainframe Modernization Service (Managed Runtime Environment experience) is no longer open to new customers. For capabilities similar to AWS Mainframe Modernization Service (Managed Runtime Environment experience) explore AWS Mainframe Modernization Service (Self-Managed Experience). Existing customers can continue to use the service as normal. For more information, see [AWS Mainframe Modernization availability change](https://docs.aws.amazon.com/m2/latest/userguide/mainframe-modernization-availability-change.html). # Deploy AWS Transform for mainframe Runtime on Amazon EC2 You can learn how to set up AWS Transform for mainframe Runtime on Amazon EC2, how to update the runtime version, how to monitor your deployment by using Amazon CloudWatch alarms, and how to add licensed dependencies with the topics in this section. These instructions are applicable when you create Amazon EC2 instances as well as when you use Amazon ECS on Amazon EC2 or Amazon EKS on Amazon EC2. Starting with alpha version 5.60.0, the AWS Transform for mainframe Runtime distribution includes a deployment folder with a comprehensive README.md file. This guide provides step-by-step Amazon EC2 deployment instructions, configuration options, and troubleshooting tips. **Topics** + [Set up AWS Transform for mainframe Runtime on Amazon EC2](ba-runtime-deploy-ec2.md) + [Upgrade the AWS Transform for mainframe Runtime on Amazon EC2](ba-runtime-maint-ec2.md) + [Set up AWS Transform for mainframe Runtime (on Amazon EC2) Amazon CloudWatch alarms](ba-cw-alarms-ec2.md) + [Set up licensed dependencies in AWS Transform for mainframe Runtime on Amazon EC2](ba-runtime-dependencies-ec2.md) # Set up AWS Transform for mainframe Runtime on Amazon EC2 This topic explains how to set up and deploy the PlanetsDemo sample application using AWS Transform for mainframe Runtime on Amazon EC2. **Topics** + [Prerequisites](#ba-runtime-deploy-prereq) + [Setting up](#ba-runtime-deploy-setup) + [Test the deployed application](#ba-runtime-deploy-test) ## Prerequisites Before you begin, make sure you complete the following prerequisites. + Configure the AWS CLI by following the steps in [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). + Complete [AWS Transform for mainframe Runtime prerequisites](ba-runtime-setup-prereq.md) and [Onboarding AWS Transform for mainframe Runtime](ba-runtime-setup-onboard.md). + Create an Amazon EC2 instance using one of the supported instance types. For more information, see [Get started with Amazon EC2 Linux instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html). + Make sure you can connect to the Amazon EC2 instance successfully, for example by using SSM. **Note** Throughout this guide, the Tomcat installation path is assumed to be `/m2-anywhere/tomcat-gapwalk/velocity`. Ensure you use this path when following the instructions below or adapt the following instruction to the path of your choice. + Download and extract AWS Transform for mainframe Runtime (on Amazon EC2) directly to the velocity directory `/m2-anywhere/tomcat-gapwalk/velocity` (the Tomcat installation folder). For instructions on how to retrieve the AWS Transform for mainframe Runtime artifacts, including information about storage, access, and content, see [AWS Transform for mainframe Runtime artifacts](ba-runtime-artifacts.md). + Download the [PlanetsDemo application archive](https://d3lkpej5ajcpac.cloudfront.net/demo/bluage/PlanetsDemo-v1.zip). + Unzip the archive and upload the application to an Amazon S3 bucket of your choice. + Create an Amazon Aurora PostgreSQL database for JICS. The AWS Transform for mainframe Runtime will automatically execute the `PlanetsDemo-v1/jics/sql/initJics.sql` script during the first startup. For information about how to create an Amazon Aurora PostgreSQL database, see [Creating and connecting to an Aurora PostgreSQL DB cluster](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_GettingStartedAurora.CreatingConnecting.AuroraPostgreSQL.html#CHAP_GettingStarted.AuroraPostgreSQL.CreateDBCluster). ## Setting up To set up the PlanetsDemo sample application, complete the following steps. 1. Connect to your Amazon EC2 instance and go to the `conf` folder under your Apache Tomcat installation folder. Open the `catalina.properties` file for editing and replace the line that starts with `common.loader` with the following line. ``` common.loader="${catalina.base}/lib","${catalina.base}/lib/*.jar","${catalina.home}/lib","${catalina.home}/lib/*.jar","${catalina.home}/shared","${catalina.home}/shared/*.jar","${catalina.home}/extra","${catalina.home}/extra/*.jar" ``` 1. Navigate to the `/m2-anywhere/tomcat-gapwalk/velocity/webapps` folder. 1. Copy the PlanetsDemo binaries available at `PlanetsDemo-v1/webapps/` folder from the Amazon S3 bucket using the following command. ``` aws s3 cp s3://path-to-demo-app-webapps/ . --recursive ``` **Note** Replace `path-to-demo-app-webapps` with the correct Amazon S3 URI for the bucket where you previously unzipped the PlanetsDemo archive. 1. Copy the content of `PlanetsDemo-v1/config/` folder to `/m2-anywhere/tomcat-gapwalk/velocity/config/`. 1. Provide the connection information for the database that you created as part of the prerequisites in the following snippet in the `/m2-anywhere/tomcat-gapwalk/velocity/config/application-main.yml` file. For more information see, [Creating and connecting to an Aurora PostgreSQL DB cluster](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_GettingStartedAurora.CreatingConnecting.AuroraPostgreSQL.html#CHAP_GettingStarted.AuroraPostgreSQL.CreateDBCluster). ``` datasource: jicsDs: driver-class-name : url: username: password: type : ``` 1. Start your Apache Tomcat server and verify the logs. ``` /m2-anywhere/tomcat-gapwalk/velocity/startup.sh tail -f /m2-anywhere/tomcat-gapwalk/velocity/logs/catalina.log ``` If you find error codes that start with a C followed by a number, such as CXXXX, note the error messages. For example, error code C5102 is a common error indicating an incorrect infrastructure configuration. ## Test the deployed application For an example of how to test the PlanetsDemo application, see [Test the PlanetsDemo application](ba-runtime-test-planetsdemo.md). # Upgrade the AWS Transform for mainframe Runtime on Amazon EC2 This guide describes how to upgrade the AWS Transform for mainframe Runtime on Amazon EC2. **Topics** + [Prerequisites](#ba-runtime-maint-prereq) + [Upgrade the AWS Transform for mainframe Runtime in the Amazon EC2 instance](#ba-runtime-maint-copy-files) + [Upgrade the AWS Transform for mainframe Runtime in a container](#ba-runtime-maint-copy-files) ## Prerequisites Before you begin, make sure you meet the following prerequisites. + To check if there are specific instructions for your version, see [Upgrading instructions for AWS Transform for mainframe](ba-migration-notes.md). + Complete [AWS Transform for mainframe Runtime prerequisites](ba-runtime-setup-prereq.md) and [Onboarding AWS Transform for mainframe Runtime](ba-runtime-setup-onboard.md). + Ensure that you have an Amazon EC2 instance with an existing AWS Transform for mainframe Runtime installation. For more information, see [Get started with Amazon EC2 Linux instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html). + Make sure you can connect to the Amazon EC2 instance successfully, for example, by using SSM. + Download the AWS Transform for mainframe Runtime version you want to upgrade to. The framework consists of two archive files : `gapwalk-x.y.z.zip` and `aws-bluage-webapps-x.y.z.zip`. For more information, see [AWS Transform for mainframe Runtime artifacts](ba-runtime-artifacts.md). ## Upgrade the AWS Transform for mainframe Runtime in the Amazon EC2 instance Complete the following steps to upgrade the AWS Transform for mainframe Runtime. 1. Connect to your Amazon EC2 instance and change the user to **su** by running the following command. ``` sudo su ``` You need superuser privilege to run commands in this tutorial. 1. To extract the binaries, use the following commands. Run the commands in each folder. ``` unzip gapwalk-x.y.z.zip unzip aws-bluage-webapps-x.y.z.zip ``` 1. Stop the Apache Tomcat services by using the following commands. ``` systemctl stop tomcat.service systemctl stop tomcat-webapps.service ``` 1. Replace the content of `/shared/` with the content of `gapwalk-x.y.z/shared/`. 1. Replace `/webapps/gapwalk-application.war` with `gapwalk-x.y.z/webapps/gapwalk-application.war`. 1. Replace the war files in `/webapps/`, namely `bac.war` and `jac.war`, with the same files from `aws-bluage-webapps-x.y.z/velocity/webapps/`. 1. Start the Apache Tomcat services by running the following commands. ``` systemctl start tomcat.service systemctl start tomcat-webapps.service ``` 1. Check the logs. To check the status of the deployed application, run the following commands. ``` curl http://localhost:8080/gapwalk-application/ ``` The following message should appear. ``` Jics application is running ``` ``` curl http://localhost:8181/jac/api/services/rest/jicsservice/ ``` The following message should appear. ``` Jics application is running ``` ``` curl http://localhost:8181/bac/api/services/rest/bluesamserver/serverIsUp ``` The response should be empty. The AWS Transform for mainframe runtime is successfully upgraded. ## Upgrade the AWS Transform for mainframe Runtime in a container Complete the following steps to upgrade the AWS Transform for mainframe Runtime. 1. Rebuild your Docker image with the desired AWS Transform for mainframe Runtime version. For instructions, see [Set up AWS Transform for mainframe Runtime on Amazon EC2](ba-runtime-deploy-ec2.md). 1. Push your Docker image to your Amazon ECR repository. 1. Stop and restart your Amazon ECS or Amazon EKS service. 1. Check the logs. The AWS Transform for mainframe Runtime is successfully upgraded. # Set up AWS Transform for mainframe Runtime (on Amazon EC2) Amazon CloudWatch alarms You can set up CloudWatch to receive your application log and add an alarm to warn you of possible errors. This allows you to have more visible notifications whenever your deployed applications encounter exceptions. The following sections help you understand and learn about the configuration of CloudWatch logging and alarm setup. ## Enable CloudWatch logging To enable CloudWatch logging, create a `logback-cloudwatch.xml` file in the config folder using the configuration template provided in the following section. Then, reference this file in the `application-main.yml` file by uncommenting the following lines: ``` # logging: # config: classpath:logback-cloudwatch.xml ``` After uncommenting these lines, CloudWatch logging will be activated and can be further configured as explained in the following sections. ## Configuration of CloudWatch logging Use the following template to create the `logback-cloudwatch.xml` file: ``` %date{yyyy-MM-dd HH:mm:ss.SSS,UTC} %level --- [%thread{15}] %logger{40} : %msg%n%xThrowable BluAgeRuntimeOnEC2-Logs %date{yyyy-MM-dd,UTC}.%instanceId.%uuid %date{yyyy-MM-dd HH:mm:ss.SSS,UTC} %level --- [%thread{15}] %logger{40} : %msg%n%xThrowable ``` Everything outside the element is standard logback configuration. There are two appenders in this file: a console appender to send logs to the console and a CloudWatch appender to send logs to CloudWatch. The `level` attribute in the `root` element specifies the logging level of the entire application. The required values inside the tag are: + :Sets the name of the log group in CloudWatch. If the value is not specified it defaults to `BluAgeRuntimeOnEC2-Logs`. If the log group doesn’t exist it will be created automatically. This behavior can be changed through configuration, which is covered below. + : Sets the name of the logStream (inside of the log group) in CloudWatch. Optional values: + : Overrides the Region that the log stream will be written to. By default, logs go to the same Region as the EC2 instance. + : The pattern the log messages will use. + : The maximum number of log messages to send to CloudWatch per operation. + : The time in milliseconds to allow for CloudWatch logs to be written. + : The time in milliseconds to try to insert requests in the internal log queue. + : The maximum size of the internal queue. + : Create log group and log stream if they don't exist. + : The amount of time that you want the thread to sleep on startup. This initial wait allows for an initial accrual of logs. + : The maximum size of a log event. Logs that exceed this size won’t be sent. + : Truncate messages that are too long. + : Enable the emergency appender. ## CloudWatch setup In order for the above configuration to correctly push logs to CloudWatch, update your Amazon EC2 IAM instance profile role to grant it additional permissions for the `BluAgeRuntimeOnEC2-Logs` log group and its log streams: + `logs:CreateLogStream` + `logs:DescribeLogStreams` + `logs:CreateLogGroup` + `logs:PutLogEvents` + `logs:DescribeLogGroups` ## Alarm setup Thanks to CloudWatch logs, you can then configure different metrics and alarms, depending on your application and your needs. Specifically, you can set up proactive alarms for usage alerts, in order to be warned in the case of errors that might put your application in a grace period (and in the end, prevent it from working at all). To achieve this, you can add a metric concerning the "Error C5001" string in the logs, which highlights errors in the connection to the AWS Transform for mainframe control system. You can then define an alarm that reacts to this metric. # Set up licensed dependencies in AWS Transform for mainframe Runtime on Amazon EC2 This guide describes how to set up additional licensed dependencies that you can use with AWS Transform for mainframe Runtime on Amazon EC2. **Topics** + [Prerequisites](#ba-runtime-dependencies-prereq) + [Installation steps](#ba-runtime-dependencies-overview) ## Prerequisites Before you begin, make sure you complete the following prerequisites. + Complete [AWS Transform for mainframe Runtime prerequisites](ba-runtime-setup-prereq.md) and [Onboarding AWS Transform for mainframe Runtime](ba-runtime-setup-onboard.md). + Make sure that you have an Amazon EC2 instance with AWS Transform for mainframe Runtime (on Amazon EC2) installed. For more information, see [Get started with Amazon EC2 Linux instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html). + Make sure you can connect to the Amazon EC2 instance successfully, for example, by using SSM. + Get the following dependencies from their sources. ### Oracle database Supply an [Oracle database driver](https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html). We tested the AWS Transform for mainframe Runtime (on Amazon EC2) functionality with version **ojdbc11-23.3.0.23.09.jar**, but a more recent version might be compatible. ### IBM MQ connection Supply an [IBM MQ client](https://www.ibm.com/support/pages/mqc91-ibm-mq-clients). We tested the AWS Transform for mainframe Runtime (on Amazon EC2) functionality with version **com.ibm.mq.jakarta.client-9.3.4.1.jar**, but a more recent version might be compatible. With this dependency version, also supply the following transitive dependencies: + bcprov-jdk15to18-1.76.jar + bcpkix-jdk15to18-1.76.jar + bcutil-jdk15to18-1.76.jar ### DDS Printer files Supply the Jasper reports library (https://community.jaspersoft.com/download-jaspersoft/community-edition). We tested the AWS Transform for mainframe Runtime (on Amazon EC2) functionality with **jasperreports-6.16.0.jar**, but a more recent version might be compatible. With this dependency version, also supply the following transitive dependencies: + castor-core-1.4.1.jar + castor-xml-1.4.1.jar + commons-digester-2.1.jar + ecj-3.21.0.jar + itext-2.1.7.js8.jar + javax.inject-1.jar + jcommon-1.0.23.jar + jfreechart-1.0.19.jar + commons-beanutils-1.9.4.jar + commons-collections-3.2.2.jar ## Installation steps To install the dependencies, complete the following steps. 1. Connect to your Amazon EC2 instance and change the user to **su** by running the following command. ``` sudo su ``` You need Superuser privilege to run commands in this tutorial. 1. Navigate to the `/extra/` folder. ``` cd /extra/ ``` 1. Copy any of the above dependencies as required at this folder. **Note** For JAC and BAC webapps with Oracle-hosted databases, ensure you include the Oracle database driver (ojdbc) in this folder. 1. Stop and start the tomcat.service by running the following commands. ``` systemctl stop tomcat.service ``` ``` systemctl start tomcat.service ``` 1. Check the status of the service to make sure it is running. ``` systemctl status tomcat.service ``` 1. Verify the logs.