Terminals installation

AWS Blu Insights Terminals runs on the customer environment. This guide focuses on how to run the Terminals jar, but it can also be launched with Docker.

Make sure you requested the tool on Blu Age Toolbox of AWS Blu Insights before moving to the next sections

Prerequisites

• Approved request of the Terminals for your AWS account in Blu Age Toolbox module.
• Java 17 needs to be installed.
• You need to have minimal IAM policies on your account to download the Terminals from S3 bucket. In case you don't have policies, then create one with the below information.

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Action": [
              "s3:ListBucket"
          ],
          "Resource": [
              "arn:aws:s3:::toolbox-terminals-bt"
          ]
      },
      {
          "Effect": "Allow",
          "Action": [
              "s3:GetObject"
          ],
          "Resource": [
              "arn:aws:s3:::toolbox-terminals-bt/*"
          ]
      }
  ]
}

Step-by-step guide

Toolbox buckets are replicated on the us-east-1 and us-east-2 regions. To use these replicated buckets, append the region to the bucket name: e.g. s3://toolbox-terminals-bt-us-east-1. Make sure to adapt your user or role policy accordingly.

1. Check that you configure the AWS credentials with the AWS account used in your request made in Blu Insights Toolbox.
2. Download Terminals last version archive using the command aws s3 cp --recursive s3://toolbox-terminals-bt/latest LOCAL_PATH
3. Unpack the archive present in LOCAL_PATH
4. Move to the unzipped archive folder.

Run with Jar

1. Run the jar from the archive folder: java -Dsecure.token=<random_token> -jar terminals-....jar
   1. token is a random text set by you. It will be used to secure requests. Example: -Dsecure.token=test .You can also set it as an environment variable: export SECURE_TOKEN=<token>
   2. The default port for the application is 8080. You can update it using -Dserver.port=<port>
2. The application will by default run on localhost:8080. If port was updated, then localhost:<port>

Run with Docker

1. Create a Dockerfile with:

   FROM amazoncorretto:17-alpine 
   COPY terminals-*.jar terminals.jar 
   CMD ["java", "-Dserver.port=80", "-jar", "/terminals.jar"]

2. Build the Docker image: docker build -t terminals .
3. Run the docker container: docker run -p 80:80 -e SECURE_TOKEN=<random_token> terminals
4. The application will run on localhost:80

Logging

The logs of the Terminals application are the CloudWatch logs of the ECS task that run it. We log by default messages of socket creation and termination, and data exchange. For more detailed logs, you can add an environment variable to the docker container named JAVA_NET_LOG_OPT.           
It points to a java option javax.net.debug=, and it takes values like all and ssl. For more information about debugging, you can visit ReadDebug and DebugBlog.