Blogs

Introduction

Nowadays, cloud computing is getting more and more popular because of the obvious time and resource saves it could provide. One of the most competent contender on the field is the Amazon Web Services which I've found easy to use and fairly cheap on low scale. Among its many features, it is able to launch instances of previously uploaded virtual machine images with merely a few clicks. With this feature, you can easily share your system configuration, possibly containing a demo of your own product, with anyone who is interested. People can easily create their own copy, try it out, evaluate, and give you instant feedback.

In this post, I will give a straightforward, step by step guide on how to create an image of a Liferay instance and how to upload and run it on the Amazon Web Service (AWS).

The article consists three parts. In the first part, I will tell you the exact way I've created my Liferay image. I will also point out the rules that one must follow in order to construct an ASW suitable image. In the second part, I will explain how to initialize the AWS tools, upload and import your image. If you already have a virtual machine image or you are pretty confident that you can create one without any help, you could jump strait to the second part. Nevertheless, be sure to check the rules at the end of part one to prevent funny surprises. In the last part, I will explain how to launch your virtual machine and how to connect to the running instance.

1. Constructing a Virtual Machine Image with Liferay

I've decided to create an Ubuntu server with the latest Liferay, running the latest, not yet published release of Valamis. Notice that these details are truly irrelevant to the scope of this article. You could deploy any kinds of themes, portlets or hooks with an example content matching your personal goals.

As for the virtual machine image file, I used Oracle's VirtualBox (VB) the create it. It is free, easy to use, well supported, runs on every major operation systems, and it produces “Open Visualization Format” by default, which is compatible with the AWS.

1.1 Create a basic Ubuntu server distribution

The title is a little bit deceiving because I didn't create anything here. As a common software developer, I'm kind of lazy, thus I've speed up the process by downloading a pre-installed Ubuntu server.

So, feel free to help yourself here.

1.2 Run the Virtual Machine and establish SSH connection

1. Import the downloaded image into the VirtualBox with File → Import Appliance.

2. Configure its network settings in order to easily access it through SSH later. Go to its Settings menu in the VB and select the Network tab. There, you should select “Bridged Adapter” with “eth0”. No other advanced settings are needed.

3. Start up the system. It will probably ask for credentials that you can check out on the page where you've downloaded the original image. If you would like to change these credentials or create new users, this would be the best time for it.

4. When you are ready to continue, hit ifconfig to read the current IP address, and connect to the server from your host machine through ssh.

   $ssh ubuntu@10.12.9.62

1.3 Install Java Runtime Environment

First of all, you will need some kind of Java Runtime Environment (JRE) on the server in order to run Liferay. I've chosen the easiest solution and installed the default JRE because it is perfectly fine for my needs. If you need something else, this page might be helpful for you.

To install the default JRE on Ubuntu, type in:

$sudo apt-get update
$sudo apt-get install default-jre

Once the installation is complete, validate it with the usual java -version

1.4 Install a database management system and create a database for Liferay

I've used a PostgreSQL server, but that is also my own personal choice. You could use any kind of database system, event Liferay's Hypersonic. In order to install PostgreSQL, type in the following:

$sudo apt-get install postgresql postgresql-contrib

That should install and start your database system.

If you have executed the following command through SSH, like I did, you've might also encountered an error message starting like this:

perl: warning: Setting locale failed.

Long story short: It has failed to set the locales thus the main cluster could not be created so in the end, the server has not been started. To fix this, you have to regenerate the locales, manually create the cluster and start the server. Execute the following commands directly from your Ubuntu server:

$sudo dpkg-reconfigure locales
$sudo pg_createcluster 9.4 main –start $sudo /etc/init.d/postgresql start

Once you have the server up and running, quickly create a database and user for your future Liferay.

$sudo -u postgres createuser -SPRD <your_user> $sudo -u postgres createdb --owner <your_user> <your_database>

1.5 Set up your Liferay

I won't go into much detail here. Just download your desired Liferay version onto your server and extract it into its appropriate location. Start it, and configure it with the previously created database on the startup screen. You can get the liferay from here.

Use scp to upload it to your server, and unzip to extract it. Navigate to the Tomcat home and type in:

$bin/startup.sh && tail -f logs/catalina.out. 

If that fails, make sure that the ownership of the files belongs to you and not to the root.

Once your Liferay operates, deploy all your themes, portlets, hooks or ext plugins, and create your example data there.

1.6 Make your Tomcat start at server startup.

Obviously, you don't want to start Tomcat manually every time the server starts. In fact, Tomcat should start up or shut down every time your server does.

You need a script to achieve that. Create it with “sudo nano /etc/init.d/tomcat” and insert the following template there. Make sure to change the value associated with the JAVA_HOME variable to your JRE's location, and insert your Tomcat's home folder to the marked places.

Next, you need to make that script executable.

$sudo chmod 755 /etc/init.d/tomcat

Last but not least, link your script to the startup folders with a symbolic link.

$sudo ln -s /etc/init.d/tomcat /etc/rc1.d/K99tomcat
$sudo ln -s /etc/init.d/tomcat /etc/rc2.d/S99tomcat

1.7 Export your Virtual Machine

Once everything is set on your virtual machine, it is time to export it. Follow these steps to do so:

1. Power it off normally.

2. Fill out its description at Settings → General → Description. The least that you should write there is the operation system's and every installed product's version number, accompanied with every credential you've made. You will have at least three of those: operation system, database and Liferay user. The point is that someone, who knows absolutely nothing about this image (for example, you 5 years from now) would be able to use it nonetheless.

3. Export it with File → Export Appliance. Select your image, select the OVF 1.0 format with ova extension and fill out a list of other descriptions before export.

Congratulations, you have a VM image that can be imported to the Amazon Web Service. Thus concludes part 1.

2. Importing your VM image into the AWS

In this second part, we will use the VM image and create a running instance on the Amazon cloud. For simplicity, when I would like to point to a specific location in the cloud's controls, I will use the Title1 → Title2 notation, and the starting point is always the main control panel. In the commands and code templates, the parts that you have to customize will be between <>.

2.1 Register to the Amazon Web Service

You can do that simple here with the “Create a Free Account” button. The registration progress is easy and straightforward, but you will need a valid credit card and a working phone number. Don't worry, the registration is free, but you will get access to tons of services which are not free.

2.2 Create a user for your account

This may sound weird at first, but you can create separate users under your account who will have only a selected subset of permissions instead of root access. This is advised for security reasons thus I will do this and so should you.

Go to Security & Identity →  Identity & Access Management →  Users and create a new user. After the user creation, there is a button named “Download Credentials” well-hidden in the bottom-right corner. I warmly recommend you to push that, since you will need those credentials pretty soon.

2.3 Install the Amazon Web Service Command Line Interface

Yes, this whole web service has its own command line interface (CLI) that you will absolutely need, since everything can be done from there.

In case you are using windows, you can use the 32-bit or 64-bit MSI installer.

If you are using Linux, you will need python to continue. Check your current python version with
python --version and install it if needed.

Then, you need to download, unzip and install the CLI.

$curl "https://s3.amazonaws.com/aws-cli/awscli-bundle.zip" 
-o "awscli-bundle.zip" 
$unzip awscli-bundle.zip $sudo ./awscli-bundle/install -i /usr/local/aws -b /usr/local/bin/aws

Test your aws installation with aws help. Further information about the CLI installation can be found here.

2.4 Configure your CLI

Remember the credentials you've downloaded in step 2.2? You will need those here to configure your CLI so that Amazon on the other end of the service will identify your person correctly.

Type in the following command with the username you've used in step 2.2 and fill out the appearing inputs.

$aws configure --profile <your_userName>

AWS Access Key ID [None]: <your_id_from_credentials>
AWS Secret Access Key [None]: <your_key_from_credentials> Default region name [None]: <your_region_code> Default output format [None]: text

You can find the valid region names here.

Your CLI should be functional now. Here you can find the reference with every possible command.

2.5 Create an S3 bucket for your image

Before you can launch your virtual machine on Amazon, it has to be uploaded. Uploaded files can be stored in Amazon's Simple Storage Service (S3), which is a scalable storage on the cloud. You need to create a special place for your image, that you will reference to later.

1. Go to Storage & Content Delivery -> S3.

2. Click on the Create Bucket button and create your bucket. Don't forget to choose the correct region.

3. Upload your VM image file there.

2.6 Create in Import Service Role for your user.

Your user will need in specific role, named vmimport in order to import your VM image. Create a file named trust-policy.json with the following content:

When have this file, you can set the role for your user with the following command:

$aws iam create-role --profile <your_user_name> --role-name vmimport 
--assume-role-policy-document file://trust-policy.json

2.7 Create a policy for your Service Role

Create a file named role-policy.json with the following template content:

Don't forget to replace <your_s3_bucket> with your bucket's name. When you have the file, execute the following command:

$aws iam put-role-policy --profile <your_user_name> --role-name vmimport 
--policy-name vmimport --policy-document file://role-policy.json

2.8 Configure your user's permissions

Navigate to your user's permissions. Go to Security & Identity → Identity & Access Management → Users → Click on user name → Permissions → Managed Policies → Attach Policy

The easiest way here is to add AdministratorAccess to your user. Its policy will look like this:

Obviously, this is not the most secure approach. If you want to restrict your user's rights, he should have at least these permissions:

Don't forget to insert your own S3 bucket's name into this template.

2.9 Import your Virtual Machine to Amazon Web Service

Finally, this glorious moment has arrived. Since you have all the required roles and permission, you can import your image. To make things more clear, create a file named upload-config.json with the following content:

You must insert your bucket name, and your image's path in the bucket. If it is in the root, just insert its filename there. Once you have this file, you can import your image:

$aws ec2 import-image --profile <your_user_name> 
--cli-input-json file://upload-config.json

The import process will take time, but after that you will be able to launch your instance on the cloud. If you are curious about the current state of your import, type in this:

 $aws ec2 describe-import-image-tasks --profile <your_user_name>

3. Managing your instance on the Amazon Web Service

In this last part, I will explain how to launch and manage your instance on the cloud.

3.1 Launch your VM on AWS

1. Locate your imported image: Compute → EC2 → Images → AMIs

2. Select you image and click on the launch.

3. Select your optimal instance type. For now, the cheapest, "t2.micro" would be the best choice.

4. Click on Review and Launch. Review your Instance's settings. Note down it's security group's name, you will need it later.

5. Click on launch, and create an SSH key-pair to your instance. You will need this key-pair in order to access your instance through SSH.

6. Click on Launch Instances, and your instances will be started for real.

3.2 Connect to your Virtual Machine through SSH

1. Locate your instance in Compute → EC2 → Instances → Instances

2. Select your running instance and click on Connect. There you can find useful information about your instance.

3. In short, connect to your server with the following command:

• $ssh -i "<your_private_key.pem>" <your_user_name>@<your_ip>

You should be able to connect your running instance through SSH, and by checking the Tomcat logs, you could verify that your Liferay is up and running.

3.3 Connect to your Liferay from the browser.

If you were inpatient and tried to access your Liferay though the browser, you must have faced a “Connection timeout” message. That is because your 8080 port is still blocked. In order to allow it, follow these steps:

• Go to Compute → EC2 → Network & Security → Security Groups

• Select the group that is used by your instance. You've noted this down in step 3.1.

• Go to Actions → Edit → Inbound rules

• Add a “Custom TCP Rule” with a Port Range 8080

• Save

Now, you should be able to connect to your liferay through the browser.

3.4 Publish your instance

If you want to share your work with the rest of the world, you can share your image at the following location: 
EC2 -> Images -> AMIs -> Your_Instance -> Permissions tab -> Edit -> Public.
This way, your license will be available under the "Community AMI's" tab when someone tries to launch a new instance. If you want to publish your work in the AWS Marketplace, that is another story.

3.5 The Environment Friendly Developer

Running instances or storing wast number of files in the cloud requires energy. Protect your environment by not wasting more energy than it is absolutely necessary. In other words: these services are hourly billed, so if you want to spare your or your company's bank account from further suffering, please stop/delete not used instances and files from the cloud.