Getting started with Wercker & Java

This guide is a step-by-step approach to developing, building and deploying a sample app with Wercker within minutes.

While this guide uses Java, the general concepts explained in this tutorial apply to every other programming language.


To be able to follow along with this guide, you will need the following things:

  • A Wercker account
  • The Wercker CLI

Note that this example application is built for Java 8 and may not work with later versions of Java.

Setting up the app

Before we can start developing, we have to fork and clone the sample app into our local development environment. After you’ve done that, cd into the project directory:

$ git clone
$ cd getting-started-java/

Next, build and run the app to verify everything is working:

$ ./gradlew bootRun

Now in your browser navigate to localhost:8080 and you should be presented with Hello World!

You can press Ctrl+C in your shell to stop the Gradle build now.

Developing the app

Now that we’ve setup our app we can start running it inside a container using wercker. Before we do that however, let’s first take a look at the wercker.yml file included in your project folder.


The wercker.yml is the only config file you need for using wercker. In it, you will define all your steps needed to successfully develop, build and deploy your application. To get started, we’re only interested in developing our app, so let’s take a closer look at the top of this file:

# The container definition we want to use for developing our app
  id: openjdk
    - "8080"

The initial box section defines two things. The id property states which container image you want to use for your project; as we’re developing in Java for this sample we’ve chosen the openjdk image. These container images are retrieved from Docker Hub if no other registry is specified. You can read more about containers here. The ports property specifies the ports that you want your running container to open. This example only requires a single port but you can specify multiple ports here if required.

Now let’s look at the dev section:

# defining the dev pipeline
    - script:
      name: gradle bootRun
      code: |
        ./gradlew bootRun

In the dev pipeline clause we define what we want to happen in our development pipeline, which in this case is just one step: script. The script step will run any arbitrary bash script we wish, in this case we’re going to use this step to start our web application.

Let’s see this step in action now and fire up our dev pipeline.

Wercker dev

In your project folder, run wercker dev --expose-ports. You should see something similar to the following output:

--> Executing pipeline
--> Running step: setup environment
Pulling from library/java: latest
Download complete: fdd5d7827f33
Download complete: a3ed95caeb02
Download complete: 0f35d0fe50cc
Download complete: 7b40647e93b7
Download complete: 95109706d468
Download complete: 938141337517
Download complete: a3ed95caeb02
Download complete: 7ff1af1d8f09
Download complete: a3ed95caeb02
Download complete: a3ed95caeb02
Download complete: a3ed95caeb02
Download complete: a3ed95caeb02
Download complete: e8a4e33c1725
Download complete: ec40bd691d34
Status: Image is up to date for java:latest
--> Running step: wercker-init
--> Running step: run gradle

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 :: Spring Boot ::        (v1.3.3.RELEASE)

Wercker first checks out your code and then sets up the container environment. This means that the container will be pulled from Docker Hub and subsequently started with access to your checked out code. It will then start executing all the steps that are defined in the wercker.yml.

If you navigate once again to localhost:8080 you should see the same output as before. The difference is that now your web application is running inside a docker container.

This is just the tip of the iceberg, there are many more steps to use for developing your app. Take a look around, and if you can’t find the step you’re looking for, you can always make your own.

Now that we’re done developing and have tested our application locally, we want to push our changes and let wercker build and deploy our app for us.

Building your app

First, let’s revisit our wercker.yml again.

# docker box definition
  id: openjdk
    - "8080"

# defining the dev pipeline
    # A step that executes `gradle bootRun` command
    - script:
      name: run gradle
      code: |
        ./gradlew bootRun

# Build definition
  # The steps that will be executed on build
    # A step that executes `gradle build` command
    - script:
        name: run gradle
        code: |
          ./gradlew --full-stacktrace -q --project-cache-dir=$WERCKER_CACHE_DIR build

Build Pipeline

We’re now interested in what’s happening the build pipeline. We’ve added a new script step here, which will run our gradle build to compile our web application. Take note that were also using the $WERCKER_CACHE_DIR environment variable to take full advantage of caching.

Wercker build

Now that we have a better understanding of our wercker.yml let’s go ahead and let wercker build our project. In your project folder, run:

$ wercker build
--> Executing pipeline
--> Running step: setup environment
pulling from library/java: latest
Pulling dependent layers: ebd45caf377c
Download complete: 64e5325c0d9d
Download complete: bf84c1d84a8f
Download complete: 87de57de6955
Download complete: 6a974bea7c0d
Download complete: 3d0d66dec985
Download complete: ec367bd67c88
Download complete: 2d87eca0ec9c
Download complete: ac13965af848
Download complete: 14182e587f2c
Download complete: 37e56f6d02a4
Download complete: 1c18d4d04737
Download complete: 66bf953cd51b
Download complete: 0dfa22e2b56d
Download complete: ebd45caf377c
Download complete: ebd45caf377c
Status: Image is up to date for java:latest
--> Running step: wercker-init
--> Running step: gradle build
--> Steps passed: 37.35s
--> Pipeline finished: 38.35s

Building locally is very useful when you’re not sure your code will run because of some changes you made. As such you don’t want to push these changes to your Git provider just yet.

But since we’ve verified that our app is compiling and running correctly, it’s time to let wercker build & deploy your app in the cloud, which is what we’ll be doing in the next section.

Adding your app to Wercker

The next step is to create a new application on wercker. Head over to and select Add application from the top menu bar.

Select the Owner and Git Provider

First we have to choose who owns the app. For this tutorial, go ahead and select yourself. If you prefer, you can select an organization you created on wercker.

Now select GitHub as your Git provider (BitBucket and GitLab are also available), and then click Next.

Select the repository

You now see a list of your existing repositories. Select the Java example you forked earlier from the list and click Next.

Configure Access

The next step is about configuring access, and the first option wercker will check out the code without using an SSH key is fine for the purpose of this tutorial, because it’s an open source and public application. So go ahead and click Next.

Review application details

Finally, once you’ve verified all the settings, click Create to complete setting up our app. Now you can trigger the first build!

Triggering your first build

The Nicely Done! screen gives you the option to generate a wercker.yml file. But as the repository already contains one, all you have to do is click trigger a build now .

The Runs page now shows a new build has been triggered! This build will do the exact same as the one you triggered locally but now everyone in your team can see and comment on the build.

Wrapping up

Congratulations! You’ve built your first app using Wercker.