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](images/Helidon_Diagram.png)
For additional information, see:
Before You Begin
To successfully complete this tutorial, you must have the following:
- 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 for the resources that you create in this tutorial.
- Sign in to the Oracle Cloud Infrastructure Console.
- Open the navigation menu and click Identity & Security. Under Identity, click Compartments.
- Click Create Compartment.
- Fill in the following information:
- Name:
<your-compartment-name>
- Description:
Compartment for <your-description>.
- Parent Compartment:
<your-tenancy>(root)
- Name:
- Click Create Compartment.
Reference: Create a compartment
2. Install an Ubuntu Linux Instance
Use the Create a VM Instance workflow to create a new compute instance.
The workflow 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 the Ubuntu Linux instance to the internet.
- Creates an
ssh
key pair you use to connect to the instance.
To get started installing an instance with the Create a VM instance workflow, follow these steps:
The steps provided are for a Free Tier account. If you are using a paid account, the steps might differ from those shown here.
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.
Follow these steps to select your VCN's public subnet and add the ingress rule.
4. Run an Application on Helidon Server
Next, set up Helidon on your Ubuntu Linux instance.
To configure the Ubuntu firewall, follow these steps:
- Open the navigation menu and click Compute. Under Compute, click Instances.
- 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.
- Open a Terminal or Command Prompt window.
- Change into the directory where you stored the
ssh
encryption keys you created in part 2. - 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. - 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.
- Run the following commands:
sudo apt update sudo apt -y install openjdk-11-jdk-headless java -version
- 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 preceding command in the current window.
source ~/.bashrc
Run the following commands:
- Install Maven.
sudo apt -y install maven
- Verify the Maven installation.
mvn --version
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:
- 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
- Change to the
helidon-quickstart-mp
directory.cd helidon-quickstart-mp
- Build the application.
mvn package
You get a message of success.
[INFO] BUILD SUCCESS
- Run the application.
java -jar target/helidon-quickstart-mp.jar
You can now test your application.
- 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. - 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. - 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.
- 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. - 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: