Get Started with Boxfuse & Executable Jar

 

This tutorial will get you started with Boxfuse and an Executable Jar. It should take you about 5-10 minutes to complete.

Prerequisites

Before you begin, ensure you have successfully:

  1. created a Boxfuse Account (simply log in with your GitHub account, it's free)
  2. downloaded and installed the latest Boxfuse Client
  3. downloaded and installed the latest version of VirtualBox
  4. downloaded and installed the latest JDK with JAVA_HOME set up correctly
  5. downloaded and installed the latest version of Maven

Creating the Executable Jar application

Start by generating a Maven jar project from an archetype:

> mvn archetype:generate -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.1 -DinteractiveMode=false -DgroupId=boxfusegetstarted -DartifactId=getstarted-executablejar -Dversion=1.0

And change to the newly created directory:

> cd getstarted-executablejar

To be able to interact with the application you'll need a web server, so go ahead and modify as boxfusegetstarted.App to look like this:

package boxfusegetstarted;

import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpHandler;
import com.sun.net.httpserver.HttpServer;

import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;

public class App {
    public static void main(String[] args) throws Exception {
        HttpServer server = HttpServer.create(new InetSocketAddress(8000), 0);
        server.createContext("/", new HttpHandler() {
            public void handle(HttpExchange t) throws IOException {
                String response = "Hello";
                t.sendResponseHeaders(200, response.length());
                OutputStream os = t.getResponseBody();
                os.write(response.getBytes());
                os.close();
            }
        });
        server.start();
    }
}

Last but not least, add the following to your pom.xml below the dependencies section to ensure the jar will be executable:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.0.2</version>
            <configuration>
                <archive>
                    <manifest>
                        <mainClass>boxfusegetstarted.App</mainClass>
                    </manifest>
                </archive>
            </configuration>
        </plugin>
    </plugins>
</build>

Now go ahead and build it:

getstarted-executablejar> mvn package

Great. Your Executable Jar application is now available under target/getstarted-executablejar-1.0.jar.

Fusing a Boxfuse image and running it locally on VirtualBox

Now it's time to fuse your application into a Boxfuse image and launch an instance of it on VirtualBox. All we need to do is specify the port we want to be exposed to the outside world:

getstarted-executablejar> boxfuse run -ports.http=8000

Creating getstarted-executablejar ...
Mapping getstartedexecutablejar-dev-myuser.boxfuse.io to 127.0.0.1 ...
Created app getstarted-executablejar (type: single-instance, db: none, logs: none)
Fusing Image for getstarted-executablejar-1.0.jar (Jar) ...
Image fused in 00:03.870s (44217 K) -> myuser/getstarted-executablejar:1.0
Launching Instance of myuser/getstarted-executablejar:1.0 on VirtualBox ...
Forwarding http port localhost:8000 -> vb-918fe0af:8000
Instance launched in 00:04.160s -> vb-918fe0af
Waiting for Payload to start on vb-918fe0af:8000 (expecting HTTP 200 at / within 300s) ...
Successfully started payload in 00:06.655s -> http://127.0.0.1:8000

Open a browser at this address to see your new application up and running within the VirtualBox VM by simply executing:

getstarted-executablejar> boxfuse open

You can also see your newly created image:

getstarted-executablejar> boxfuse ls

Images available locally:
+-------------------------------------+----------------------------------+-------+---------------------+--------------+---------+---------------------+
| Image                               |             Payload              | Debug |       Runtime       |    Ports     |  Size   |    Generated at     |
+-------------------------------------+----------------------------------+-------+---------------------+--------------+---------+---------------------+
| myuser/getstarted-executablejar:1.0 | getstarted-executablejar-1.0.jar | false | Java 8.102.14 (Jar) | http -> 8000 | 44217 K | 2016-11-25 12:33:37 |
+-------------------------------------+----------------------------------+-------+---------------------+--------------+---------+---------------------+
Total: 1

As well as the instance that is running:

getstarted-executablejar> boxfuse ps

Running Instances on VirtualBox in the dev environment :
+-------------+-------------------------------------+---------------------+-----------------------+---------------------+
|  Instance   |               Image                 |        Type         |          URL          |     Launched at     |
+-------------+-------------------------------------+---------------------+-----------------------+---------------------+
| vb-918fe0af | myuser/getstarted-executablejar:1.0 | 2 CPU / 1024 MB RAM | http://127.0.0.1:8000 | 2016-11-25 12:33:42 |
+-------------+-------------------------------------+---------------------+-----------------------+---------------------+
Total: 1

Deploying your application to AWS

Now let's deploy the image to AWS. As Boxfuse works with your AWS account, it first needs the necessary permissions to do so. So if you haven't already done it, go to the Boxfuse Console and connect your AWS account now.

Every new Boxfuse account comes with 3 environments: dev, test and prod. dev is your local VirtualBox environment and test and prod are on AWS.

So let's deploy our application to the prod environment on AWS:

getstarted-executablejar> boxfuse run getstarted-executablejar:1.0 -env=prod

Pushing myuser/getstarted-executablejar:1.0 ...
Verifying myuser/getstarted-executablejar:1.0 ...
Waiting for AWS to create an AMI for myuser/getstarted-executablejar:1.0 in eu-central-1 (this may take up to 50 seconds) ...
AMI created in 00:55.661s in eu-central-1 -> ami-014b8f6e
Creating security group boxsg-myuser-prod-getstarted-executablejar ...
Creating Elastic IP ...
Mapping getstartedexecutablejar-myuser.boxfuse.io to 35.156.118.52 ...
Creating security group boxsg-myuser-prod-getstarted-executablejar-1.0 ...
Launching t2.micro instance of myuser/getstarted-executablejar:1.0 (ami-014b8f6e) in prod (eu-central-1) ...
Instance launched in 00:19.085s -> i-fdabcc40
Creating Cloud Watch Alarm for Instance auto-recovery -> i-fdabcc40-auto-recovery-alarm
Waiting for AWS to boot Instance i-fdabcc40 and Payload to start at http://54.93.94.108:8000/ ...
Payload started in 00:10.046s -> http://54.93.94.108:8000/
Associating Elastic IP 35.156.118.52 to i-fdabcc40 ...
Waiting 15s for AWS to complete Elastic IP Zero Downtime transition ...
Successfully deployed myuser/getstarted-executablejar:1.0 in prod at http://getstartedexecutablejar-myuser.boxfuse.io:8000/

Notice that Boxfuse has reused your image unchanged instead fusing a new one.

With that one command Boxfuse has automatically pushed your image to the Boxfuse Vault as well as provisioned, configured and secured all necessary AWS resources. There is no manual work necessary on your behalf.

All you need to do is simply navigate to your new domain to see your Executable Jar application in action on AWS:

Bonus: update your application with zero downtime

Now let's take things one step further and deploy an update of your application with zero downtime using blue/green deployments.

Start by modifying boxfusegetstarted.App and change the response:

String response = "Hello " + t.getRequestURI().getPath().substring(1) + ", welcome to Boxfuse!";

then bump the version in pom.xml:

<version>1.1</version>

and rebuild the jar:

getstarted-executablejar> mvn clean package

Finally deploy the new version of your application to AWS:

getstarted-executablejar> boxfuse run -ports.http=8000 -env=prod

Fusing Image for getstarted-executablejar-1.1.jar (Jar) ...
Image fused in 00:03.779s (44217 K) -> myuser/getstarted-executablejar:1.1
Pushing myuser/getstarted-executablejar:1.1 ...
Verifying myuser/getstarted-executablejar:1.1 ...
Waiting for AWS to create an AMI for myuser/getstarted-executablejar:1.1 in eu-central-1 (this may take up to 50 seconds) ...
AMI created in 01:04.464s in eu-central-1 -> ami-3167a35e
Creating security group boxsg-myuser-prod-getstarted-executablejar-1.1 ...
Launching t2.micro instance of myuser/getstarted-executablejar:1.1 (ami-3167a35e) in prod (eu-central-1) ...
Instance launched in 00:14.913s -> i-d083e46d
Creating Cloud Watch Alarm for Instance auto-recovery -> i-d083e46d-auto-recovery-alarm
Waiting for AWS to boot Instance i-d083e46d and Payload to start at http://54.93.32.88:8000/ ...
Payload started in 00:09.081s -> http://54.93.32.88:8000/
Reassociating Elastic IP 35.156.124.198 from i-fdabcc40 to i-d083e46d ...
Waiting 15s for AWS to complete Elastic IP Zero Downtime transition ...
Destroying Cloud Watch Alarm i-fdabcc40-auto-recovery-alarm ...
Terminating instance i-fdabcc40 ...
Destroying Security Group sg-ffa38697 (boxsg-myuser-prod-getstarted-executablejar-1.0) ...
Successfully deployed myuser/getstarted-executablejar:1.1 in prod at http://getstartedexecutablejar-myuser.boxfuse.io:8000/

And there it is:

Summary

In this brief guide we have seen how to:

  • create an Executable Jar application
  • fuse it into a Boxfuse image
  • deploy the image locally on VirtualBox
  • deploy the image unchanged to AWS
  • update the application with zero downtime

Now it's your turn. Take your favorite Executable Jar application and deploy it with ease and pleasure.

And don't forget, Boxfuse also comes with a Maven and a Gradle plugin to seamlessly integrate with your CI/CD workflow.

Boxfuse Executable Jar Documentation