Get Started with Boxfuse & Dropwizard

 

This tutorial will get you started with Boxfuse and Dropwizard. 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 Dropwizard application

Creating a new Dropwizard app is incredibly easy. You can use the Dropwizard Maven archetype to create all the necessary scaffolding:

> mvn archetype:generate -B -DarchetypeGroupId=io.dropwizard.archetypes -DarchetypeArtifactId=java-simple -DarchetypeVersion=0.9.1 -DgroupId=getstarted -DartifactId=hello -Dversion=1.0 -Dpackage=hello -Dname=Hello

Adding a resource and healthcheck

Now change to the newly created directory:

> cd hello

Adding the resource

To be able to interact with the application you'll need a resource, so go ahead and create one as src/main/java/hello/resources/HelloResource.java with the following contents:

package hello.resources;

import com.google.common.base.Optional;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import java.util.HashMap;
import java.util.Map;

@Path("/")
@Produces(MediaType.APPLICATION_JSON)
public class HelloResource {
    private final String template;

    public HelloResource(String template) {
        this.template = template;
    }

    @GET
    public Map<String, Object> sayHello(@QueryParam("name") Optional<String> name) {
        Map<String, Object> result = new HashMap<>();
        result.put("hello", String.format(template, name.or("stranger")));
        return result;
    }
}

Adding the healthcheck

For the healthcheck, add a file named src/main/java/hello/health/TemplateHealthCheck.java:

package hello.health;

import com.codahale.metrics.health.HealthCheck;

public class TemplateHealthCheck extends HealthCheck {
    private final String template;

    public TemplateHealthCheck(String template) {
        this.template = template;
    }

    @Override
    protected Result check() throws Exception {
        final String greeting = String.format(template, "TEST");
        if (!greeting.contains("TEST")) {
            return Result.unhealthy("template doesn't include a name");
        }
        return Result.healthy();
    }
}

Putting it all together

Finally register both the resource and the healthcheck in the hello.HelloApplication.run() method:

@Override
public void run(final HelloConfiguration configuration, final Environment environment) {
    String template = "Hello, %s!";
    environment.jersey().register(new hello.resources.HelloResource(template));
    environment.healthChecks().register("template", new hello.health.TemplateHealthCheck(template));
}

And that's it. You now have a basic Dropwizard application we can use with the following structure:

 hello
   src
     main
       java
         hello
           api
           cli
           client
           core
           db
           health
             TemplateHealthCheck.java
           resources
             HelloController.java
           HelloApplication.java
           HelloConfiguration.java
       resources
         assets
         banner.txt
     test
       java
         hello
           api
           client
           core
           db
           resources
       resources
         fixtures
   pom.xml

Your application is now fully set up. Go ahead and build it:

hello> mvn package

Great. Your Dropwizard application is now available under target/hello-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:

hello> boxfuse run

Fusing Image for hello-1.0.jar ...
Image fused in 00:07.997s (55691 K) -> myuser/hello:1.0
Launching Instance of myuser/hello:1.0 on VirtualBox ...
Forwarding admin-http port localhost:8081 -> vb-239113a0:8081
Forwarding http port localhost:80 -> vb-239113a0:80
Instance launched in 00:03.663s -> vb-239113a0
Waiting for Payload to start on Instance vb-239113a0 ...
Payload started in 00:06.688s -> http://127.0.0.1:10080

Boxfuse has automatically detected the Dropwizard configuration and used the :8081/healthcheck endpoint to check whether the instance came up correctly.

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

hello> boxfuse open

You can also see your newly created image:

hello> boxfuse ls

Images available locally:
+------------------+---------------+-------+---------+------------+--------------------------------+---------+---------------------+
| Image            |    Payload    | Debug |  Java   | AppServer  |             Ports              |  Size   |    Generated at     |
+------------------+---------------+-------+---------+------------+--------------------------------+---------+---------------------+
| myuser/hello:1.0 | hello-1.0.jar | false | 8.60.22 | Dropwizard | admin-http -> 8081, http -> 80 | 55691 K | 2015-11-26 22:37:07 |
+------------------+---------------+-------+---------+------------+--------------------------------+---------+---------------------+
Total: 1

As well as the instance that is running:

hello> boxfuse ps

Running Instances on VirtualBox in the dev environment :
+-------------+------------------+---------------------+------------------+---------------------+
|  Instance   |      Image       |        Type         |       URL        |     Launched at     |
+-------------+------------------+---------------------+------------------+---------------------+
| vb-239113a0 | myuser/hello:1.0 | 4 CPU / 1024 MB RAM | http://127.0.0.1 | 2015-11-26 22:37:16 |
+-------------+------------------+---------------------+------------------+---------------------+
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:

hello> boxfuse run -env=prod

Creating myuser/hello ...
Pushing myuser/hello:1.0 ...
Verifying myuser/hello:1.0 ...
Waiting for AWS to create an AMI for myuser/hello:1.0 in eu-central-1 (this may take up to 50 seconds) ...
AMI created in 00:42.569s in eu-central-1 -> ami-8d776ae1
Creating Elastic IP ...
Mapping hello-myuser.boxfuse.io to 52.29.49.4 ...
Creating security group boxsg-myuser-prod-hello-1.0 ...
Launching t2.micro instance of myuser/hello:1.0 (ami-8d776ae1) in prod (eu-central-1) ...
Instance launched in 00:35.621s -> i-549833e8
Waiting for AWS to boot Instance i-549833e8 and Payload to start at http://52.28.52.131:8081/healthcheck ...
Payload started in 00:52.041s -> http://52.28.52.131:8081/healthcheck
Remapping Elastic IP 52.29.49.4 to i-549833e8 ...
Waiting 15s for AWS to complete Elastic IP Zero Downtime transition ...
Deployment completed successfully. myuser/hello:1.0 is up and running at http://hello-myuser.boxfuse.io/

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 Dropwizard 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 hello.HelloApplication.run() and change the template:

String template = "Updated by Boxfuse with zero downtime, %s!";

then bump the version in pom.xml:

<version>1.1</version>

and rebuild the jar:

hello> mvn clean package

Finally deploy the new version of your application to AWS:

hello> boxfuse run -env=prod

Fusing Image for hello-1.1.jar ...
Image fused in 00:07.450s (55691 K) -> myuser/hello:1.1
Pushing myuser/hello:1.1 ...
Verifying myuser/hello:1.1 ...
Waiting for AWS to create an AMI for myuser/hello:1.1 in eu-central-1 (this may take up to 50 seconds) ...
AMI created in 00:50.998s in eu-central-1 -> ami-7074691c
Creating security group boxsg-myuser-prod-hello-1.1 ...
Launching t2.micro instance of myuser/hello:1.1 (ami-7074691c) in prod (eu-central-1) ...
Instance launched in 00:20.545s -> i-ff9f3443
Waiting for AWS to boot Instance i-ff9f3443 and Payload to start at http://52.29.102.135:8081/healthcheck ...
Payload started in 00:56.214s -> http://52.29.102.135:8081/healthcheck
Remapping Elastic IP 52.29.49.4 to i-ff9f3443 ...
Waiting 15s for AWS to complete Elastic IP Zero Downtime transition ...
Terminating instance i-549833e8 ...
Destroying Security Group sg-37aaef5e ...
Deployment completed successfully. myuser/hello:1.1 is up and running at http://hello-myuser.boxfuse.io/

And there it is:

Summary

In this brief guide we have seen how to:

  • create a Dropwizard 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 Dropwizard application and deploy it with ease and pleasure.

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

Boxfuse Dropwizard Documentation