Free Tier: Set up Helidon on an Ubuntu Instance

In this tutorial, you use an Oracle Cloud Infrastructure Free Tier account to set up an Ubuntu compute instance. Then, you set up a Helidon MicroProfile (MP) server for your host.

Key tasks include how to:

  • Set up a compartment for your development work.
  • Install your Ubuntu Linux instance and connect it to your Virtual Cloud Network (VCN).
    • Set up an Oracle Cloud Infrastructure virtual cloud network and related network services required for your host to connect to the internet.
    • Set up ssh encryption keys to access your Ubuntu Linux Server.
  • Configure ingress rules for 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 Instance.

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 complete this tutorial, you must have the following:

Requirements
  • An Oracle Cloud Infrastructure Free Tier account. Start for Free.
  • A MacOS, Linux, or Windows computer with ssh support installed.

1. Set up a Compartment for Development

Configure a compartment for your development.

Create a Compartment

Create a compartment for the resources that you create in this tutorial.

  1. Log in to the Oracle Cloud Infrastructure Console.
  2. Open the navigation menu and click Identity & Security. Under Identity, click Compartments.
  3. Click Create Compartment.
  4. Fill in the following information:
    • Name: <your-compartment-name>
    • Description: Compartment for <your-description>.
    • Parent Compartment: <your-tenancy>(root)
  5. Click Create Compartment.

Reference: Create a compartment

2. Install your Ubuntu Linux Instance

Use the Create a VM Instance wizard to create a new compute instance.

The wizard does several things when installing the instance:

  • Creates and installs a compute instance running Ubuntu Linux.
  • Creates a VCN with the required subnet and components needed to connect your Ubuntu Linux instance to the internet.
  • Creates an ssh key pair you use to connect to your instance.
Review Installation Steps

To get started installing your instance with the Create a VM instance wizard, follow these steps:

  1. From the main landing page, select Create a VM instance wizard. Quick action menu from the main Free Tier landing page

    The Create compute instance page is displayed. It has a section for Placement, Image and shape, Networking, Add SSH keys, and Boot volume.

  2. Choose the Name and Compartment.

    Initial Options

    • Name: <name-for-the-instance>
    • Create in compartment: <your-compartment-name>

    Enter a value for the name or leave the system supplied default.

  3. Review the Placement settings.
    • Click Edit.
    • Click the Show advanced options link.
    • Take the default values.

    Your data might look similar to the following:

    Availability domain

    • Availability domain: AD-1
    • Capacity type: On-demand capacity
    • Fault domain: Let Oracle choose the best fault domain
    Note

    For Free Tier, use Always Free Eligible option for availability domain.
  4. Review the Image and shape settings.
    1. Select the latest Ubuntu image.
      1. Click Edit.
      2. Click Change image.
      3. Select the latest Ubuntu image.
      4. Click Select image. Your image is displayed, for example your data looks similar to the following:

        Image

        • Image: Canonical Ubuntu 20.04
        • Image build: <current-build-date>
    2. Take the default values for Shape.

      For example, your data looks similar to the following:

      Shape

      • Shape: VM.Standard.E2.1.Micro
      • OCPU: 1
      • Memory (GB): 1
      • Network bandwidth (Gbps): 0.48
      Note

      For Free Tier, use Always Free Eligible shape options.
  5. Review the Networking settings. Take the default values provided by the wizard.
    Note

    The following is sample data. The actual values change over time or differ in a different data center.
    • Virtual cloud network: vcn-<date>-<time>
    • Subnet: vcn-<date>-<time>
    • Assign a public IPv4 address: Yes
  6. Review the Add SSH keys settings. Take the default values provided by the wizard.
    • Select the Generate a key pair for me option.
    • Click Save Private Key and Save Public Key to save the private and public SSH keys for this compute instance.

    If you want to use your own SSH keys, select one of the options to provide your public key.

    Note

    Put your private and public key files in a safe location. You cannot retrieve keys again after the compute instance has been created.
  7. Review the Configure boot volume settings. Take the default values provided by the wizard.

    Leave all check boxes unchecked.

  8. Click Create to create the instance. Provisioning the system might take several minutes.
You have successfully created an Ubuntu Linux instance.

3. Enable Internet Access

The Create a VM Instance wizard automatically creates a VCN for your VM. You add an ingress rule to your subnet to allow internet connections on port 8080.

Create an Ingress Rule for your VCN

Follow these steps to select your VCN's public subnet and add the ingress rule.

  1. Open the navigation menu and click Networking, and then click Virtual Cloud Networks.
  2. Select the VCN you created with your compute instance.
  3. With your new VCN displayed, click <your-subnet-name> subnet link.

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

  4. Click the Default Security List link.

    The default Ingress Rules for your VCN are displayed.

  5. Click Add Ingress Rules.

    An Add Ingress Rules dialog is displayed.

  6. Fill in the ingress rule with the following information.

    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: Allow HTTP connections

    Click Add Ingress Rule. Now HTTP connections are allowed. Your VCN is configured for Apache server.

  7. Click Add Ingress Rules.
    Now HTTP connections are allowed. Your VCN is configured for Apache server.
You have successfully created an ingress rule that makes your instance available from the internet.

4. Run an Application on Helidon Server

Next, set up Helidon on your Ubuntu Linux instance.

Configure the Ubuntu Firewall

To configure the Ubuntu firewall, follow these steps:

  1. Open the navigation menu and click Compute. Under Compute, click Instances.
  2. Click the link to the instance you created in the previous step.

    From the Instance Details page look under the Primary VNIC section. Copy the public IP address the system created for you. You 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 2.
  5. Connect to your instance 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 instance, this command logs you into your instance. You can now issue sudo commands to install and start your server.

  6. Update firewall settings.

    The Ubuntu firewall is disabled by default. However, you must update your iptables configuration to allow HTTP traffic. Run the following commands:

    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.

Install OpenJDK
  1. Run the following commands:
    sudo apt update
    sudo apt -y install openjdk-11-jdk-headless
    java -version
  2. 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
  3. Activate the preceding command in the current window.
    source ~/.bashrc
Install Apache Maven

Run the following commands:

  1. Install Maven.
    sudo apt -y install maven
  2. Verify the Maven installation.
    mvn --version
Install Helidon

Run the following Maven Archetype which creates a Maven project template to start with. This project uses the Helidon MP Quickstart example from the Helidon website. Run the following commands:

  1. Run Helidon Maven install. For example:
    mvn -U archetype:generate -DinteractiveMode=false \
        -DarchetypeGroupId=io.helidon.archetypes \
        -DarchetypeArtifactId=helidon-quickstart-mp \
        -DarchetypeVersion=2.2.1 \
        -DgroupId=io.helidon.examples \
        -DartifactId=helidon-quickstart-mp \
        -Dpackage=io.helidon.examples.quickstart.mp

    The Archetype creates a Maven project under the current directory. Your output is similar to the following:

    [INFO] Project created from Archetype in dir: /home/ubuntu/helidon-quickstart-mp
    [INFO] BUILD SUCCESS
    Note

    To install the latest version of Helidon MP, see Helidon MP Quickstart
  2. Change to the helidon-quickstart-mp directory.
    cd helidon-quickstart-mp
  3. Build the application.
    mvn package

    You get a message of success.

    [INFO] BUILD SUCCESS
  4. Run the application.
    java -jar target/helidon-quickstart-mp.jar
Test your Helidon Application

You can now test your application.

  1. From a new terminal, connect to your Ubuntu instance 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 instance: http://<x.x.x.x>:8080/greet

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

  2. 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 see {"message":"Hello Mike!"} on your instance, or in your browser.

  3. Update the greeting. From the terminal, enter:
    curl -X PUT -H "Content-Type: application/json" -d '{"greeting" : "Aloha"}' http://localhost:8080/greet/greeting

    The command updates the Hello in the message to Aloha.

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

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

  5. 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 service, on your Oracle Cloud Infrastructure instance.

References:

For detailed information on this example, see Helidon MP Quickstart

What's Next

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

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