First steps in the Home at Cloud PaaS

Installing the PaaS client

To work with the PaaS platform provided by Home at Cloud, you need to have a client installed, via which the communication and interaction with Cloud Foundry (CF) cloud application platform API is realized. We install the client in the local environment where the application code we want to deploy to Cloud Foundry is/will be located. If you’re just testing the platform, for running the Cloud Foundry client, we recommend using a small test VPS or a virtual machine within the Public Cloud service, or a local virtual machine (for example, using VirtualBox). The Cloud Foundry client (cf-cli) installation guide is available, for example, on the Cloud Foundry website. We recommend installing client version 6.20.0 (e.g. using sudo apt-get install cf-cli=6.20.0 command). In the case of the Linux Debian operating system, the client can be installed via the package manager in the following way:

  1. Adding the public Cloud Foundry Foundation GPG key to the trustworthy keys list:
    sudo wget -q -O - https://packages.cloudfoundry.org/debian/cli.cloudfoundry.org.key | sudo apt-key add -
  2. Adding the Cloud Foundry CLI package repository to the trustworthy software sources list:
    sudo echo "deb https://packages.cloudfoundry.org/debian stable main" | sudo tee /etc/apt/sources.list.d/cloudfoundry-cli.list
  3. Updating the available software sources list:
    sudo apt-get update
  4. Installing the Cloud Foundry cf-cli client:
    sudo apt-get install cf-cli=6.20.0
  5. Validating proper client installation:
    cf --version

If the client is installed correctly, the output of the previous command displays the version of the client installed. In such a case, we can move on to logging in to Cloud Foundry, which is necessary for working with PaaS.

Logging in to the PaaS

Now you have the Cloud Foundry client (cf-cli) installed. To work with PaaS, at first it is necessary to log in to your PaaS/Cloud Foundry provider environment. When signing in, you need to enter:

  • the PaaS / Cloud Foundry provider (API endpoint) – api.paas.homeatcloud.cz
  • user name (Email) – you can find it in the „Ordered PaaS service has been established“ email
  • password – you can find it in the „Ordered PaaS service has been established“ email

To log in to Cloud Foundry, we use the cf login command and enter the required information. Upon successful login, we will gain access to the appropriate organization and space within Cloud Foundry. The PaaS Provider creates a temporary authentication token, so you do not have to re-enter the login information during further use of the client. Logging in again will be required after the authentication token expires. If necessary, we can log out using the cf logout command. Now we are successfully logged into the PaaS/Cloud Foundry, and we can enter the commands in the cf <command> style, which the cf-cli client formats and sends to the Cloud Foundry/PaaS provider.

If we use the cf command without another command/parameter, cf-cli displays the basic help which we can also call with cf -h, cf -help or cf help. If we want to page the output of the help command, we can redirect it to the less command (cf -help | less) and then move through using the arrow keys, space, PageUp, PageDown, etc. In order to view the full output of the help, we use the cf help -a command.

PaaS_2

Deploying an application in PaaS

If we are logged in to Cloud Foundry, we can deploy a sample Java application. The showcase scenario of deploying an application into Cloud Foundry includes deploying a test application from the Debian operating system. In this demo, we will use the Spring Music test application (catalog of music albums with basic CRUD functions).

PaaS_3

The code of this application is available in the GitHub repository, from which, using the git command, we clone it to the location where we have installed the cf-cli client. Firstly, we install the git tool using the sudo apt install git command. Then we can clone the sample application code using the git clone https://github.com/cloudfoundry-samples/spring-music command. Now the application code is available within the machine where the previously installed cf-cli client is located.

Since it is an application written in the Java programming language, it is necessary to compile the code first. For these purposes, we will need OpenJDK, which we install with sudo apt install openjdk-8-jdk. We now move to the application code directory using the cd spring-music command. We initiate the start of the application build using the ./gradlew clean assemble command. After a successful build, an application package is available, which we can deploy into Cloud Foundry.

Now all that needs to be executed is the cf push command, which ensures that the container is created, application deployed and run. Successful application deployment can be verified by the cf apps command, which should output the application called spring-music.

PaaS_4

The application is now publicly available via the address listed in the urls column in the cf apps command output, which can be verified by running the web browser and opening the URL in the browser.

As mentioned before, the backend services are provided externally. Therefore, if we push the application that needs a backend service to run, the application deployment may fail. In such case, it is advisable to execute cf push with the −−no−start parameter, which will ensure the application is deployed, yet not started. Afterwards, the service can be bound to the application, and the application can be started manually.

If you would need to log in to the virtual machine terminal or, more precisely, to the container within which the application is running, then simply use cf ssh <app_name> command. From the application terminal, you can log out using the exit command.

Basic application lifecycle management

The application is running and available to users. Here are some other commands that can be useful when managing an application lifecycle:

APPLICATION MANAGEMENT

  • List running apps: cf apps
  • List routes which recieve requests: cf routes
  • Show the logs of the running app: cf logs −−recent
  • Stop the app: cf stop <app_name>
  • Start the app: cf start <app_name>
  • Restart an app (all of its instances): cf restart <app_name>
  • Scale the app:
    • Scale the number of the app instances: cf scale <app_name> -i <int>
    • Scale the app disk: cf scale <app_name> -k <1024 MB | 1G | …>
    • Scale the app memory: cf scale <app_name> -m <1024 MB | 1G | …>
  • Application variables management:
    • List the app variables: cf env <app_name>
    • Set an app variable: cf set-env <app_name>
    • Delete an app variable: cf unset-env <app_name>
  • Deleting an application:
    • Delete an app, not its route: cf delete <app_name>
    • Delete both the app and its route: cf delete <app_name> -r
    • Delete both the app and its route without any confirmation: cf delete <app_name> -r -f

SERVICE MANAGEMENT

  • List available service providers: cf m
  • List available service plans: cf m -s <service_name>
  • Create service instance: cf create-service <service_name> <service_plan> <service_instance_name>
  • List (ordered) services instances: cf services
  • Show the (ordered) service instance information: cf service <service_instance_name>
  • Bind the service instance to the application: cf bind-service <app_name> <service_instance_name>
  • Unbind the service from the application: cf unbind-service <app_name> <service_instance_name>
  • Remove the service instance: cf delete-service <service_instance_name>

PaaS_5

Using backend services in applications

As mentioned above, in the case of the cloud applications, the backend services (database systems, message queue, etc.) are neither included in the cloud applications nor are they included in the container where the application is running but, on the contrary, they are provided externally through service brokers. Next, we will show you how to provide the backend service for the application. We will assume that we are logged in to the PaaS and that our application is deployed and running. Firstly, we will display a list of available services brokers using cf m command. As we can see in the following picture, one of the services available is the PostgreSQL relational database system. Using the cf m -s postgres command, we will display the available plans of the service. Then we create a new instance of the PostgreSQL service using the cf create-service postgres standard my_postgres command. You can verify the successful creation of the service instance using the cf services command, and show the service instance detail using the cf my_postgres command.

In order for the service to be accessible from the application, we need to bind it to the application. This is done using the cf bind-service spring-music my_postgres command, where spring-music represents the name of the application and my_postgres represents the name of the service instance we assign to the application. We validate the successful assignment of the service instance to the application using the cf services command whose output will show the application that we have assigned the service instance to in the bound apps column. However, the assigned service instance will not be accessible by the application until the appropriate environment variables containing the access data for that service instance are passed to the application. Fortunately, the PaaS will arrange that for us, and it will suffice when we execute the cf restage spring-music command in order to re-deploy the application for which the service instance will already be accessible. We can verify that the environment variables containing the access data of the given service instance are available to the application by the cf env spring-music command.

If we remove the app, the service instance will continue to exist. If we want to delete it, we use the cf delete-service my_postgres command. If the instance is bound to any application, this connection will be removed. Therefore, it is a good idea to execute cf restage on relevant applications after deleting the service instance or even better to remove the service binding to the application before deleting the service instance using the cf unbind-service <app_name> <service_instance> command. We can then verify the successful removal of the service using the cf services command.

As far as the MySQL or the MariaDB database is concerned, a cf-cli plugin is available in PaaS, which can be installed with the cf install-plugin -r “CF-Community” mysql-plugin command and used for logging into the provided instance of the given database. For these purposes, we must have mysql-client installed on the machine where cf-cli is installed and from where we log into the PaaS (if not installed, you can install it using the sudo apt install mysql-client command). Then, in order to log into the database, (provided that you are logged into the PaaS), just execute the cf mysql <mysql_service_name> command. Successful login is indicated by a change from the shell prompt to the database client prompt.

PaaS_6

Conclusion

For help with other commands related to application scaling, setting environment variables, etc., use cf help -a, and search for help to specific commands or look into documentation pages. Of course, you can also contact us. If you encounter any problem when testing or using PaaS, do not hesitate to leave us a message or call us.