Introduction and Prerequisites

This exercise is to

• Learn basic usage of a Platform as a Service (PaaS) infrastructure.
• Learn how to deploy, scale and monitor your applications.

In this exercise you will create an account on Pivotal Web Services and set up the tools to use the CloudFoundry environement. Next you will deploy, configure and run a simple web application and learn how to deploy, scale, restart and debug your instances as well as explore the resilience features of a PAAS. In the second part you will deploy a more complex application and learn how to attach and manage persistence services and routes.

The following resources and tools are required for this exercise session:

• Java JDK 1.7 or newer
• Account on Pivotal Web Services (PWS) - see instructions to create below
• Cloud Foundry command line client (CLI) - see instructions to install below

The code for this exercise is provided on Moodle in a single ZIP file.

• Create a local directory as your working directory for this exercise and unzip the contents of the file TSM-ClComp_Lab_PAAS.zip (see end of this document) in it.

Time

The entire session will take 90 minutes.

Task 1 - Prepare the environment

Create an account on Pivotal Web Services

Pivotal Web Services (PWS) is a public PaaS offering based on CloudFoundry (running on AWS). The free account on PWS will provide you with a credit of $87, which should be plenty enough to complete this exercise. Most of the services offer a free plan, which also are sufficient to complete the exercise.

• To create your account, go to https://run.pivotal.io and click on "SIGN UP FOR FREE", click on Create Account and fill in the account information.

• In the next step you need to confirm your email address, by clicking on the link sent to you in a verification email.

• The link will forward you to the last step, which is to request a code to get your free credit. For this you need to enter your mobile phone number, to which the code will be sent by SMS (each phone number can only be used once).

After logging in, an Organization and Space (development) is automatically created for you. Organizations and spaces can be used to organize and separate applications and services from each other. A typical structure is to have separate spaces for development, testing and production of an application.

Install CloudFoundry command line client (CLI)

Even though you can do a lot of the operations via the web UI, it is very convenient to use the command line interface to work with Cloud Foundry. Specifically, to automate your deployment process e.g. by using a CI/CD- Service.

Follow the instructions on http://docs.cloudfoundry.org/cf-cli/install-go-cli.html to download and install the CloudFoundry command line interface (CLI) and install the package.

Login to Pivotal Web Services (Cloud Foundry)

Next you need to connect your client to the Cloud Foundry target environment. In this exercise this is Pivotal Web Services, but it works similar for any Cloud Foundry instance.

• Set the target environment to the API endpoint of PWS:

  $ cf api https://api.run.pivotal.io
  

  and login using your credentials

  $ cf login
  

  (enter email and password when asked & select org and space)

• Explore the commands and options of the cf CLI using

  $ cf help
  

  You can always get detailed info for a command using

  $ cf help <command>
  

Task 2 - Deploy your first application (cf-demo)

In this task we will deploy a very simple Groovy application.

Change to the cf-demo directory in your working directory for this exercise.

You can now deploy a first version of your application using the simple command

$ cf push

The system will automatically detect that it is a Groovy application. Thereafter the application will be sent to the server, where it is staged and deployed to the specified number of containers. Cloud Foundry uses Language specific build-packs for this. A build-pack contains instructions how to build and package an application. In our case the client automatically detects that it is a Groovy application and is using the Java build-pack.

• Try to find out, using the cf CLI, what build-packs are available on PWS by default? (Hint: try cf help buildpacks)

• How to specify a build-pack explicitly? (http://docs.run.pivotal.io/buildpacks/)

For deployment, the manifest.yml file contains the important parameters declaring how to run the application. Without a manifest file you would need to specify all the parameters using the command line tool.

• What is the effect of the parameter random-route: true?

• What is the URL under which your app is available?

• You may set a fixed host name with a parameter host: cf-demo-<teamNo> to make it available under a consistent URL.

The application is showing some basic runtime instance information.

Open a second terminal window, change to the application directory and use the command cf logs ... to display the log messages of the application.

Next, scale the application to run three instances using the CLI. Use cf help to find the correct command. Within a minute three instances should be running.

• Check the changing instance number when reloading the page in the browser and the status of the instances using the command $ cf app cf-demo

Kill an instance using the x button in the console.

• Check the log and verify the app

  $ cf app cf-demo 
  

  and see if the health manager is restoring the state.

The CLI supports installing plugins (http://docs.cloudfoundry.org/cf-cli/use-cli-plugins.html). A list of interesting community plugins can be found here: http://plugins.cloudfoundry.org/ui/. In the following you will install a plugin to present and dig into some metrics and statistics about running application; similar to the top command on unix to show metrics about processes (install and usage instructions can be found on https://github.com/ECSTeam/cloudfoundry-top-plugin).

• Check if the CF-Community plugin repo is already bound:

  $ cf list-plugin-repos
  

• If not, add it using:

  $ cf add-plugin-repo CF-Community http://plugins.cloudfoundry.org/
  

• Install the plugin:

  $ cf install-plugin -r CF-Community "top"
  

• Use the plugin:

  $ cf top
  

• What details are available about your app(s)? What other statistics (beside your applications) do you get?

• See options using:

  $ cf help top
  

Congratulations! You have deployed, scaled and monitored your first application.

• Make a screenshot of the running application and the output of the statistics plugin and put it into the report.

• Stop your application if you don't need it anymore. Running applications (assigned RAM) and services are billed against your credit.

Task 3 - Install spring-music MVC Application and attach a service

In this section you will deploy a larger MVC application and attach an external service to persistently store your data.

Change to the spring-music directory in your working directory for this exercise.

Instructions to compile and deploy the application to Cloud Foundry can be found in the README.md file of the project.

In the spring-music directory build the application (war-file) using the command

$ ./gradlew clean assemble

This compiles and packages the application in the spring-music.war file in the subdirectory ./build/libs/. The first time you run the command it will take some time to download the build tool and all dependencies.

Next you will deploy the application. Similar to the previous application the manifest.yml contains the deployment parameters.

• Update the manifest.yml file to choose a random domain name instead of a fixed one.
• Deploy it using cf push

Test your application; see the connected DB and service in the info link (blue 'i' in a white circle at the top right).

• Where is the data stored?
• Does it persist between application restarts?

Now it is time to bind your application to a persistent data-store. Cloud Foundry offers a marketplace containing all the available services the platform provider offers:

• What services are available in the marketplace?

• Create a DB instance (e.g. ElephantSQL/turtle for Postgres) using

  $ cf create-service ...
  

• and bind it to your application using

  $ cf bind-service ...
  

• You may have to restart the application to use the new SQL DB; see the connected DB and service in the info Link (top right)

Your application may also be available under multiple URLs. This can be achieved using routes.

• Study the create-route, map-route, unmap-route and delete-route commands using cf help and add a second route (e.g. myfancymusicapp-<teamNo>.cfapps.io) to your application.

• You can check the configured links using the commands cf routes or cf apps.

Congratulations! You have deployed an app and attached a service to store your data persistently.

• Make a screenshot of the running application and the output of the info page and put them into the report.

Task 4 - Connect your app to an analytics server (optional)

New Relic is an online analytics server which gives you insights on how your application is performing. It gives you warnings if your application is not available or specified performance thresholds are triggered.

• Create a New Relic service instance and bind it to your spring-music application.

• Restage or redeploy your application to see it sending requests to the New Relic service

• Check the New Relic service (through the Manage action on the service page) and inspect the service performance.

• Try to find out how to configure New Relic to monitor your application and send you emails, if your application fails.

• (Before closing the exercise make sure to remove your triggers and delete the service in New Relic.)

Cleanup

At the end of the exercise please make sure to stop all applications, purge all unused routes and unbind and delete the services to save credit for future usage.

Additional Documentation

Cloud Foundry documentation can be found on the following pages:

• Cloud Foundry documentation: http://docs.cloudfoundry.org
• Pivotal documentation: http://docs.run.pivotal.io