Running Hyperon-Studio in AWS

Requirements:

• Running PostgreSQL database instance (it is also possible to use Amazon RDS service or H2 file database instead).

1. Launch the AMI

• To get started, visit the Amazon Marketplace. In the search bar that appears, enter Hyperon Studio and press Enter.
• Choose Hyperon-Studio entry.
• On the main page, you can read basic information about Hyperon Studio. Click Continue to subscribe and read Terms and Conditions. After getting yourself familiar with the license, click Continue to configuration.
• On the next screen, you can choose the Hyperon Studio versionand region you want to launch your instance in. Next, click Continue to launch.
• Select Launch through EC2 in the Choose Action section. This step is required to be able to specify the user-data script, which allows passing environment variables to the application without the need to log in to the instance.

2. Define required properties

2.1 Environment properties

To set up environment variables for containers we can:

1. manually create a /home/ec2-user/environment.conf file with variable we need (seebelow).
2. prepare user-data-script like in the example below:

Content-Type: multipart/mixed;boundary="//"
MIME-Version: 1.0 

--//
Content-Type: text/cloud-config;charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;filename="cloud-config.txt" 

#cloud-config
cloud_final_modules:
- [scripts-user, always] 

--//
Content-Type: text/x-shellscript;charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;filename="userdata.txt" 

#!/bin/bash
/bin/echo AWS_ACCESS_KEY_ID="YOUR_AWS_KEY_ID" >> /home/ec2-user/environment.conf
/bin/echo AWS_SECRET_KEY="YOUR_SECRET" >> /home/ec2-user/environment.conf
--//--

You can inject this script directly to your container in EC2 console using: Actions> Instance settings > Edit user data button. More about: bootstrapping AWS containers.

There is a bunch of properties you can pass, but the most important are:

• AWS_ACCESS_KEY_ID and AWS_SECRET_KEY you will be able to generate from your IAM page.Both are needed if you want to use your AWS Parameter Store to pass your configuration.
• If you don’t want to use AWS Parameter Store simply turn this off with AWS_PARAMSTORE_ENABLED=FALSE .
• HYPERON_DATABASE_URL, HYPERON_DATABASE_USERNAME, HYPERON_DATABASE_PASSWORD also need to be passed if you decided not to use AWS Parameter Store.

2.2  AWS Systems Manager Parameter Store

By default, Hyperon Studio uses AWS Systems Manager Parameter Store to fetch properties at the start of the application. You should specify AWS_ACCESS_KEY_ID and AWS_SECRET_KEY in the user-data script to connect to the AWS Systems Manager Parameter Store. If you do not define those properties, Hyperon Studio will not launch.

Required properties for hyperon studio values:

key: /config/hyperon-studio/hyperon.database.username
description: username for application’s connection to the dedicated database
value: admin

key: /config/hyperon-studio/hyperon.database.password
description: password for application’s connection to the dedicated database
value: admin

key: /config/hyperon-studio/hyperon.database.url
description: JDBC address of dedicated postgresql database
value: jdbc:postgresql://address_to_your_postgressql_server:port/postgres?currentSchema=public

If you prefer to connect to H2 database inorder notto setting up a stand alone database you can set up following properties.

key: /config/hyperon-studio/hyperon.database.url
value: jdbc:h2:/home/ec2-user/hyperon.test.db;AUTO_SERVER=TRUE;NON_KEYWORDS=VALUE

key: /config/hyperon-studio/hyperon.database.username
value: sa         

key: /config/hyperon-studio/hyperon.database.password
value: sa

‍‍2.3 Properties customization precedence

Hyperon Studio allows you to define properties in several locations. The properties are processed in the order as defined below; this implies that the last one overwrites other overlapping properties if you define the same property in two different locations.

• /home/ec2-user/conf/application.properties
• /home/ec2-user/hyperon-studio/conf/mpp-sensitive.properties
• /home/ec2-user/hyperon-studio/conf/application.properties
• /home/ec2-user/application.properties
• /home/ec2-user/hyperon-studio/conf/hyperon.properties
• “HYPERON_CONFIG_PATH” environment variable (can be defined in user-data script)
• environment variables (from/home/ec2-user/environment.conf)
• AWS Systems Manager Parameter Store

3. Instance Launch Options

• version - by default you should launch the latest version available on Amazon Marketplace. It's highly recommended that you always run the newest version of the software to ensure that stability fixes are in place.
• region- select the region you would like to launch your instance in. The image is available in all of Amazon's publicly available regions.
• EC2 Instance Type - Select the instance type you would like to use for your launched Hyperon Studio.
• Security Groups - Expose ports to access EC2 instances and Hyperon Studio: TCP 22 – SSH - used to administrate your instance remotely. TCP 38080 – default port for Hyperon Studio, this is the port on which you can access Hyperon Studio.
• Key pair settings - generate or use an existing one key and secret pair that will be needed later to access the EC2 instance.

4. Log in to the container

In order to log in you can use the following command:

ssh-i PATH_TO_PEM_FILE ec2-user@IP_HERE

You need to use a PEM file with a public key downloaded while creating the EC2instance. Type the ssh command in the terminal (Powershell on Windows or any other able to use ssh program).

Applicationis deployed at /home/ec2-user/hyperon-studio-X.X.X where X.X.X is the version of deployed hyperon studio.  

5. Manage the service

5.1 Systemd

Systemd service is configured to manage the Hyperon Tomcat instance. Therefore, you can use systemctl commands to, e.g., start, stop, enable, disable or check status such as:

sudo systemctl status/start/stop/restart hyperon-studio

5.2 Application logs

• all logs path:/home/ec2-user/hyperon-studio-x.x.x/logs/
• container logs:/home/ec2-user/hyperon-studio-x.x.x/logs/catalina.out
• appliation logs: /home/ec2-user/hyperon-studio-x.x.x/logs/catalina.out

6. Log in to running Hyperon Studio

6.1. Find an admin’s temporary password

• login to your deployed container with ssh -i PATH_TO_PEM_FILE ec2-user@IP_HERE command .
• grep a string ‘Copy password’ in the log file using:

grep ‘Copy password’ /home/ec2-user/hyperon-studio-X.X.X/logs/hyperon.log

• as a result, you will find a similar string: Copy password from file 'gifzWEZl' in home directory where the filename is different every time hyperon is bootstrapped. This file contains an admin user password.
• open this file and copy its content.

6.2 Open Hyperon Studio

• go to your browser and open a page http://IP_HERE:38080/hyperon/app‍
• pass username: admin and password: copied string here.
• Hyperon-Studio will ask you to change your temporary password.
• After that, you can login to hyperon as an admin with a new set password.                 

6. Supported Databases

Hyperon supports various SQL databases, including PostgreSQL, Oracle, H2, and Microsoft SQL. By default, we have built the AMI with PostgreSQL and H2 support. This means that the PostgreSQL and H2 JDBC drivers are present in the Tomcat lib directory, and we only expect you to provide the URL and credentials for the database.

If you want to connect to another database, then add a proper JDBC driver to the Tomcat lib directory, which is located under the path: /home/ec2-user/hyperon-studio/lib .

After the driver is added, update properties to the new database.