Free Tier: Set up Helidon on an Ubuntu VM

In this tutorial, you use an Oracle Cloud Infrastructure Free Tier account to setup an Ubuntu 18.04 virtual machine (VM). Then, you you set up Helidon with a MicroProfile (MP) server for your host. Key tasks include how to:

  • Setup ssh encryption keys to access your Ubuntu Server.
  • Setup an Oracle Cloud Infrastructure virtual cloud network (VCN) and related network services required for your host to connect to the internet.
  • Install your Ubuntu 18.04 VM and connect it to your VCN.
  • Install JDK and Maven.
  • Set up Helidon with MicroProfile (MP) server.
  • Create a Hello World Java application.
  • Test your application.

Here is a simplified diagram of the setup for your Linux VM.

A diagram of the components needed to run a Helidon MicroProfile server on Oracle Cloud Infrastructure

For additional information, see:

Before You Begin

To successfully perform this tutorial, you must have the following:

  • An Oracle Cloud Infrastructure Free Tier account. See Oracle Cloud Free Tier.
  • SSH support:
    • A MacOS or Linux computer with ssh support installed.
    • A Windows machine with Git Bash installed. See Git for Windows to download Git Bash.

1. Create SSH Encryption Keys

Create ssh encryption keys you can use to log into your VM.

  1. If you are using MacOS or Linux, open a terminal window in the directory where you want to store your keys, and issue the following OpenSSH command:
    ssh-keygen -t rsa -N "" -b 2048 -C <my-key> -f <my-key>

    The command generates some random text art used to generate the keys. When complete, you should have two files:

    • The private key file: <my-key>
    • The public key file: <my-key>.pub

    You use these files to connect to your Compute instance.

  2. On Windows, right click on the directory where you want to store your keys, select Git Bash Here, and then issue the following OpenSSH command:
    ssh-keygen -t rsa -N "" -b 2048 -C <my-key> -f <my-key>

    The command generates some random text art used to generate the keys. When complete, you should have two files:

    • The private key file: <my-key>
    • The public key file: <my-key>.pub

    You use these files to connect to your Compute instance.

You have generated the required encryption keys.

See Creating a Key Pair for more detailed information on generating ssh encryption keys.

2. Create your Virtual Cloud Network (VCN)

Setup a VCN to connect your Ubuntu instance to the internet. You configure all the components needed to create your virtual network.

  1. From the main landing page, select Set up a network with a wizard. Quick action menu from the main Free Tier landing page
  2. In the Start VCN Wizard workflow, select VCN with Internet Connectivity and then click Start VCN Wizard .
  3. In the configuration dialog, fill in the VCN Name for your VCN. Your Compartment is already set to its default value of <your-tenancy> (root).
  4. In the Configure VCN and Subnets section, keep the default values for the CIDR blocks:
    • VCN CIDR BLOCK: 10.0.0.0/16
    • PUBLIC SUBNET CIDR BLOCK: 10.0.0.0/24
    • PRIVATE SUBNET CIDR BLOCK: 10.0.1.0/24
    Note

    Notice the public and private subnets have different network addresses.
  5. For DNS RESOLUTION uncheck USE DNS HOSTNAMES IN THIS VCN.Picture shows the USE DNS HOSTNAMES IN THIS VCN option is unchecked.
  6. Click Next.

    The Create a VCN with Internet Connectivity configuration dialog is displayed (not shown here) confirming all the values you just entered.

  7. Click Create to create your VCN.

    The Creating Resources dialog is displayed (not shown here) showing all VCN components being created.

  8. Click View Virtual Cloud Network to view your new VCN.

    Your new VCN is displayed. Now you need to add a security rule to allow HTTP connections on port 8080, the default port for Helidon applications.

  9. With your new VCN displayed, click your Public subnet link.

    The public subnet information is displayed with the Security Lists at the bottom of the page. There should be a link to the Default Security List for your VCN.

  10. Click on the Default Security List link.

    The default Ingress Rules for your VCN are displayed.

  11. Click Add Ingress Rules.

    An Add Ingress Rules dialog is displayed.

  12. Fill in the ingress rule with the following information. Once all the data is entered, click Add Ingress Rules

    Fill in the ingress rule as follows:

    • Stateless: Checked
    • Source Type: CIDR
    • Source CIDR: 0.0.0.0/0
    • IP Protocol: TCP
    • Source port range: (leave-blank)
    • Destination Port Range: 8080
    • Description: Access Flask applications

    Once you click Add Ingress Rule, HTTP connections are allowed to your public subnet.

You have successfully created a VCN that will make your Java applications created through the Helidon MicroProfile server, available from the internet.

3. Install your Ubuntu VM

Install your Ubuntu VM to host your Helidon server.

  1. From the Oracle Cloud Infrastructure main menu, select Compute, then Instances.
  2. From the list of instances screen click Create Instance.

    The Create Compute Instance dialog is displayed. Notice the Show Shape, Network and Storage Options should be expanded to configure the virtual machine.

  3. Fill in the fields for the Create Compute Instance dialog with the following data:

    Initial Options

    • Name of your Instance: <name-for-the-instance>
    • Image or Operating System (Click Change Image): Canonical Ubuntu 18.04
    • Availability Domain: <Select-a-domain>
    • Instance Shape: VM.Standard.E2.1.Micro: Virtual Machine, 1 core OCPU, 1 GB Memory, 0.48 Gbps network bandwidth (the default)

    Configure Networking

    • VIRTUAL CLOUD NETWORK COMPARTMENT: (take default)
    • VIRTUAL CLOUD NETWORK: <VCN-you-created>
    • SUBNET COMPARTMENT: (take default)
    • SUBNET: <public-subnet-you-created>
    • USE NETWORK SECURITY GROUPS TO CONTROL TRAFFIC: Unchecked
    • ASSIGN A PUBLIC IP ADDRESS: Selected/Checked

    Additional Options

    • Boot Volume: All options Unchecked
    • Add SSH Keys: Add the public key file (.pub) you created in part 1 of this tutorial.
  4. Click Create to create the instance.

    Provisioning the system may take several minutes.

You have successfully created an Ubuntu Linux VM to run your Java applications on a Helidon MicroProfile server.

4. Run an Application on Helidon Server

Next, set up Helidon on your Ubuntu Linux VM.

By default, Ubuntu 18.04 does not come with Java or Maven. To setup Helidon, perform the following steps:

  1. From the main menu select Compute then Instances.
  2. Click the link to the instance you created in the previous step.

    From the Instance Details page look under the Primary VNIC Information section. Copy the public IP address the system created for you. You will use this IP address to connect to your instance.

  3. Open a Terminal or Command Prompt window.
  4. Change into the directory where you stored the ssh encryption keys you created in part 1.
  5. Connect to your VM with this ssh command
    ssh -i <your-private-key-file> ubuntu@<x.x.x.x>

    Since you identified your public key when you created the VM, this command should log you into your VM. You can now issue sudo commands to install and start your server.

  6. Update firewall settings.
    The Ubuntu firewall is disabled by default. However, it is still necessary to update your iptables configuration to allow HTTP traffic. Execute the following commands to update iptables.
    sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 8080 -j ACCEPT
    sudo netfilter-persistent save

    The commands add a rule to allow HTTP traffic through port 8080 and saves the changes to the iptables configuration files.

  7. Install JDK 11.
    sudo apt update
    sudo apt install openjdk-11-jdk-headless
    java -version
    Note

    You may need to type "y" a few times to accept the packages that are installed to the VM.
  8. Set JAVA_HOME in .bashrc.

    Update the file:

    vi .bashrc

    In the file, append the following text and save the file:

    # set JAVA_HOME
    export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

    Activate the above command in the current window.

    source ~/.bashrc
  9. Next, install Apache Maven 3.6+.
    sudo apt install maven
    mvn --version
  10. Run the following Maven Archetype which creates a Maven project template to start with. This project uses the helidon-quickstart-mp example from the Helidon website.
    mvn archetype:generate -DinteractiveMode=false \
        -DarchetypeGroupId=io.helidon.archetypes \
        -DarchetypeArtifactId=helidon-quickstart-mp \
        -DarchetypeVersion=1.4.4 \
        -DgroupId=io.helidon.examples \
        -DartifactId=helidon-quickstart-mp \
        -Dpackage=io.helidon.examples.quickstart.mp

    The Archetype creates a Maven project under the current directory. You should get the following output:

    [INFO] Project created from Archetype in dir: /home/ubuntu/helidon-quickstart-mp
    [INFO] BUILD SUCCESS
    
  11. Change to the helidon-quickstart-mp directory.
    cd helidon-quickstart-mp
  12. Build the application.
    mvn package

    You should get a message of success.

    [INFO] BUILD SUCCESS
  13. Run the application.
    java -jar target/helidon-quickstart-mp.jar
  14. You can now test your application.
    From a new terminal, connect to your Ubuntu VM with your SSH keys, and then in the command line enter:
    curl -X GET http://localhost:8080/greet
    Or, you can connect your browser to the public IP address assigned to your VM: http://<x.x.x.x>:8080/greet.

    You should see {"message":"Hello World!"} on your VM, or in your browser.

  15. Enter a name for the greeting.
    From the terminal, enter:
    curl -X GET http://localhost:8080/greet/Mike
    Or, from your browser, enter: http://<x.x.x.x>:8080/greet/Mike.

    You should see {"message":"Hello Mike!"} on your VM, or in your browser.

  16. Update the greeting.

    From the terminal, enter:

    curl -X PUT -H "Content-Type: application/json" -d '{"greeting" : "Aloha"}' http://localhost:8080/greet/greeting

    This updates the Hello in the message to Aloha.

  17. Test the updated greeting.
    From the browser, enter: http://<x.x.x.x>:8080/greet/Mike.

    You should see {"message":"Aloha Mike!"} on your VM, or in your browser.

  18. Enter the following commands in your browser to get health and metrics.
    http://<x.x.x.x>:8080/health
    http://<x.x.x.x>:8080/metrics
    To get metrics in JSON, from the terminal, enter:
    curl -H 'Accept: application/json' -X GET http://localhost:8080/metrics

Congratulations! You have successfully created a Hello World application using the Helidon MicroProfile sevice, on your Oracle Cloud Infrastructure VM.

References:

What's Next

You have successfully created a Hello World application using the Helidon MicroProfile service, on your Oracle Cloud Infrastructure VM.

To explore more information about development with Oracle products check out these sites: