Software Engineering

Hello World from Pivotal Cloud Foundry

In this blogpost, we are going to configure a simple Spring Boot Application with a REST API providing an endpoint which will return a String message saying: Hello World from Pivotal Cloud Foundry! In addition, we will set the returning message as an environment variable. Let’s skip any further introduction and just jump in!

What do we need? 

  • An IDE of your choice (Spring Tool Suite, IntelliJ, …)
  • The cf CLI installed, which is explained here
  • A Pivotal Web Services account, which can be created for free here

Let’s bootstrap our application

On start.spring.io we can easily create and download a Java project containing everything we need. You can choose Maven or Gradle as your Build-Management-Tool since both are fine for succeeding here. Java will be our programming language of choice and we choose one of the latest Spring Boot versions which is 2.1.5 at the time of writing. I will package my project as a JAR file and set the version of Java to 12. You may add any project metadata you like. I named my artifact hello-from-pcf. The only dependency we will add here is the Web dependency for using Spring MVC and Tomcat. Your configuration should look similar to this:

By clicking Generate Project we can download our project as a ZIP file. Let’s unzip it, put it in the workspace of our IDE and open our project in there.

Add of Controller and Environment Variables  

Thanks to the Spring Initializr we just used, we already have a functional Spring Boot Application which we can boot locally. Our browser should show us a Whitelabel Error Page when we run the app and hit the endpoint. You should be able to access the application via localhost:8080/.

Let’s add a Java class called HelloWorldController next to the Application class in order to make something happen there. Like this:

@RestController
public class HelloWorldController {

    @Value("${hello.world.variable:No Env-Variable set!}")
    private String message;

    @GetMapping
    public String greeting(){
        return message;

    }
}

It will create a REST endpoint, which handles requests coming in just by adding @RestController on our class. Our method greeting denoted by the @GetMapping annotation handles GET requests and will return a String called message which we have initialized as a class variable. By using the @Value annotation, the String will be passed in from an environment variable. If no environment variable was found, the String will be No Env-Variable set! by default. You may check it by cleaning, building and accessing the application again.

In order to set our environment variable, let’s go to our application.properties file which was also created by the Spring Initializr and is located in src/main/resources. All we have to do here is to put this single line:

hello.world.variable=Hello World from the local environment!

Now, if you start the App again you will see the expected String when you hit the endpoint within your browser. At this point, our App is already done and we are ready to push it to Pivotal Cloud Foundry.

Bringing it to the Cloud

Open your command line interface and run cf login in order to reach your created PWS account. Having typed in your credentials with this as your endpoint you should be able to see your Cloud Foundry space up in the cloud by running cf target. If you have to reach your CF organization or space just login here to get their names. Now you have to run a cf push command from the directory of your project with any name your app should be called, a path to your JAR file and the route to your app. Your command should look quite similar to this:

cf push hello-pcf-app -p build/libs/hello-from-pcf-0.0.1-SNAPSHOT.jar --random-route

My app is called hello-pcf-app and its JAR file is in the build/libs directory of my project since I was using Gradle. It should be in /target if you’ve used Maven. By setting –random-route we let Cloud Foundry decide about it and it will find any free route for us. You can see PCF creating the route, staging your app, downloading several buildpacks in order to find the right one for your app and finally start it.

If it’s crashing, it might be because of an older Java runtime version running on the server. You can see the latest logs by running the cf logs hello-pcf-app –recent command. If you catch something like a UnsupportedClassVersionError in there you have to run the following command in order to tell PCF to download the correct JDK version when staging the app. We’ll come back to more information about the cf set-env command in just a second. 

cf set-env hello-pcf-app JBP_CONFIG_OPEN_JDK_JRE '{ jre: { version: 12.+ } }'

You may run cf restage hello-pcf-app afterwards. Now, by running cf apps you can see all your running apps and their corresponding URLs. If you hit the URL of your app you should see a message saying: Hello World from the local environment! But since our app is no longer running locally, we have to override this value stored in our application.properties file. We can do so by setting an environment variable which will be picked up before the one set in application.properties according to Springs Documentation about Externalized Configuration.

Final Configuration of our Cloud Environment

All we have to do here is to use the cf set-env command again which will need the name of our app, the name of the environment variable we want to set and its value. By the way, if you run any cf command followed by –help it will give you great information about its usage. In this case your command should look like this or even slightly different:

cf set-env hello-pcf-app HELLO_WORLD_VARIABLE 'Hello World from Pivotal Cloud Foundry!'

Afterwards, your cf CLI will give you the hint to restage your app – follow this hint! When it’s done and you hit the endpoint again you should finally see Pivotal Cloud Foundry greeting the World.

I hope this will give you a basic knowledge for playing around with Spring Boot, PCF and environment variables – enjoy!