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 containers on Amazon ECS and Amazon EKS You can use the topics in this section to learn how to set up AWS Transform for mainframe Runtime on containers to deploy it on Amazon ECS (managed by Amazon EC2 or AWS Fargate), and Amazon EKS managed by Amazon EC2, how to update the runtime version, how to monitor your deployment by using Amazon CloudWatch alarms, and how to add licensed dependencies. **Note** This is not compatible with Amazon EKS managed by AWS Fargate. **Topics** + [Set up AWS Transform for mainframe Runtime on container](ba-runtime-deploy-container.md) + [Upgrade the AWS Transform for mainframe Runtime on container](ba-runtime-maint-container.md) + [Set up Amazon CloudWatch alarms for AWS Transform for mainframe Runtime on container](ba-cw-alarms-container.md) + [Set up licensed dependencies in AWS Transform for mainframe Runtime on container](ba-runtime-dependencies-container.md) # Set up AWS Transform for mainframe Runtime on container This topic explains how to set up and deploy the PlanetsDemo sample application using AWS Transform for mainframe Runtime on a docker container. AWS Transform for mainframe Runtime on container is available for Amazon ECS managed by Amazon EC2, Amazon ECS managed by AWS Fargate, and Amazon EKS managed by Amazon EC2. It isn't compatible with Amazon EKS managed by AWS Fargate. **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). + Download the AWS Transform for mainframe Runtime binaries. For instructions, see [Onboarding AWS Transform for mainframe Runtime](ba-runtime-setup-onboard.md). + Download the Apache Tomcat binaries. + Download the [PlanetsDemo application archive](https://d3lkpej5ajcpac.cloudfront.net/demo/bluage/PlanetsDemo-v1.zip). + Create an Amazon Aurora PostgreSQL database for JICS, and run the `PlanetsDemo-v1/jics/sql/initJics.sql` query on it. 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. After downloading the Apache Tomcat binaries, extract the contents, and go to the `conf` 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. Compress the Apache Tomcat folder by using the tar command to build a `tar.gz` archive. 1. Prepare a [Dockerfile](https://docs.docker.com/engine/reference/builder/) to build your custom image based on the provided runtime binaries and Apache Tomcat server binaries. See the following example Dockerfile. The goal is to install Apache Tomcat, followed by AWS Transform for mainframe Runtime (for Amazon ECS managed by AWS Fargate) extracted at the root of Apache Tomcat installation directory, and then to install the sample modernized application named PlanetsDemo. **Note** The contents of install-gapwalk.sh and install-app.sh scripts, which are used in this example Dockerfile, are listed after the Dockerfile. ``` FROM --platform=linux/x86_64 amazonlinux:2 RUN mkdir -p /workdir/apps WORKDIR /workdir COPY install-gapwalk.sh . COPY install-app.sh . RUN chmod +x install-gapwalk.sh RUN chmod +x install-app.sh # Install Java and AWS CLI v2-y RUN yum install sudo java-17-amazon-corretto unzip tar -y RUN sudo yum remove awscli -y RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" RUN sudo unzip awscliv2.zip RUN sudo ./aws/install # Installation dir RUN mkdir -p /usr/local/velocity/installation/gapwalk # Copy PlanetsDemo archive to a dedicated apps dir COPY PlanetsDemo-v1.zip /workdir/apps/ # Copy resources (tomcat, blu age runtime) to installation dir COPY tomcat.tar.gz /usr/local/velocity/installation/tomcat.tar.gz COPY aws-bluage-runtime-4.x.x.zip /usr/local/velocity/installation/gapwalk/gapwalk.zip # run relevant installation scripts RUN ./install-gapwalk.sh RUN ./install-app.sh EXPOSE 8080 EXPOSE 8081 # ... WORKDIR /bluage/tomcat.gapwalk/velocity # Run Command to start Tomcat server CMD ["sh", "-c", "sudo bin/catalina.sh run"] ``` The following are the contents of `install-gapwalk.sh.` ``` # Vars TEMP_DIR=/bluage-on-fargate/tomcat.gapwalk/temp # Install echo "Installing Gapwalk and Tomcat" sudo rm -rf /bluage-on-fargate mkdir -p ${TEMP_DIR} # Copy AWS Transform for mainframe runtime and tomcat archives to temporary extraction dir sudo cp /usr/local/velocity/installation/gapwalk/gapwalk.zip ${TEMP_DIR} sudo cp /usr/local/velocity/installation/tomcat.tar.gz ${TEMP_DIR} # Create velocity dir mkdir -p /bluage/tomcat.gapwalk/velocity # Extract tomcat files tar -xvf ${TEMP_DIR}/tomcat.tar.gz -C ${TEMP_DIR} # Copy all tomcat files to velocity dir cp -fr ${TEMP_DIR}/apache-tomcat-10.x.x/* /bluage/tomcat.gapwalk/velocity # Remove default webapps of Tomcat rm -f /bluage-on-fargate/tomcat.gapwalk/velocity/webapps/* # Extract AWS Transform for mainframe runtime at velocity dir unzip ${TEMP_DIR}/gapwalk.zip -d /bluage/tomcat.gapwalk # Remove temporary extraction dir sudo rm -rf ${TEMP_DIR} ``` The following are the contents of `install-app.sh`. ``` #!/bin/sh APP_DIR=/workdir/apps TOMCAT_GAPWALK_DIR=/bluage-on-fargate/tomcat.gapwalk unzip ${APP_DIR}/PlanetsDemo-v1.zip -d ${APP_DIR} cp -r ${APP_DIR}/webapps/* ${TOMCAT_GAPWALK_DIR}/velocity/webapps/ cp -r ${APP_DIR}/config/* ${TOMCAT_GAPWALK_DIR}/velocity/config/ ``` 1. Provide the connection information for the database that you created as part of the prerequisites in the following snippet in the `application-main.yml` file, which is located in the `{TOMCAT_GAPWALK_DIR}/config` folder. 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. Build and push the image to your Amazon ECR repository. For instructions, see [Pushing a Docker image](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html) in the Amazon Elastic Container Registry User Guide. Then, depending on your situation, either create an Amazon EKS pod or an Amazon ECS task definition using your Amazon ECR image, and deploy it to your cluster. For example on creating these, see [Creating a task definition using the console](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-task-definition.html) in the *Amazon Elastic Container Service (Amazon ECS) Developer Guide* and [Deploy a sample application](https://docs.aws.amazon.com/eks/latest/userguide/sample-deployment.html) in the *Amazon EKS User Guide*. 1. Specifically, for **Amazon ECS managed by AWS Fargate** case, when creating the Task definition, use the IAM role you created as part of the initial Infrastructure setup. Then, while creating the service, expand the **Networking** section, and configure the VPC, subnets, and security group that you created as part of the initial Infrastructure setup. See, [Infrastructure setup requirements for AWS Transform for mainframe Runtime ](https://docs.aws.amazon.com/m2/latest/userguide/ba-infrastructure-setup.html). ## 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 container This guide describes how to upgrade the AWS Transform for mainframe Runtime on container. To do this, you need to first complete some prerequisites, and then work with Docker image to upgrade the AWS Transform for mainframe Runtime. **Topics** + [Prerequisites](#ba-runtime-maint-prereq) + [Upgrade the AWS Transform for mainframe Runtime](#ba-runtime-maint-copy-files) ## Prerequisites Before you begin, make sure you meet 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). + Download the version of the AWS Transform for mainframe Runtime that you want to upgrade to. For more information, see [Onboarding AWS Transform for mainframe Runtime](ba-runtime-setup-onboard.md). The framework consists of two binary files: `aws-bluage-runtime-x.y.z.zip` and `aws-bluage-webapps-x.y.z.zip`. ## Upgrade the AWS Transform for mainframe Runtime 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 container](ba-runtime-deploy-container.md). 1. Push your Docker image to your Amazon ECR repository. 1. Stop and restart your Amazon ECS or Amazon EKS service. 1. Verify the logs. The AWS Transform for mainframe Runtime is successfully upgraded. # Set up Amazon CloudWatch alarms for AWS Transform for mainframe Runtime on container You can set up CloudWatch to have more visible notifications whenever your deployed applications encounter exceptions. This helps you to monitor your application log redirected to CloudWatch, and add an alarm to warn you of possible errors. ## Alarm setup With CloudWatch logs, you can configure any number of metrics and alarms, depending on your application and your needs. Specifically, you can set up proactive alarms for usage alerts directly during your cluster creation, so that you get notified when errors occur. To highlight errors in the connection to the AWS Transform for mainframe control system, add a metric concerning the string "Error C" in the logs. You can then define an alarm that reacts to this metric. # Set up licensed dependencies in AWS Transform for mainframe Runtime on container This topic describes how to set up additional licensed dependencies that you can use with AWS Transform for mainframe Runtime on container. **Topics** + [Prerequisites](#ba-runtime-dependencies-prereq) + [Overview](#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). + Get the following dependencies from their source. ### Oracle database Supply an [Oracle database driver]( https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html). For example, **ojdbc11-23.3.0.23.09.jar**. ### IBM MQ connection Supply an [IBM MQ client](https://www.ibm.com/support/pages/mqc91-ibm-mq-clients). For example, **com.ibm.mq.jakarta.client-9.3.4.1.jar**. 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). For example, **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 ## Overview To install the dependencies, complete the following steps. 1. Copy any of the above dependencies as required to your Docker image build folder. 1. If your JICS database is hosted on Oracle, provide the Oracle database driver in `your-tomcat-path/extra`. 1. On your Dockerfile, copy these dependencies to `your-tomcat-path/extra`. 1. Build your Docker image, and then push it to Amazon ECR. 1. Stop and restart your Amazon ECS or Amazon EKS service. 1. Check the logs.