+

Search Tips  |   Advanced Search

Cloud Foundry

Getting Started Tutorial

Last updated: 2018-11-27

This tutorial uses a sample app to demonstrate how to connect a Cloud Foundry application in IBM Cloud to an IBM Cloud Messages for RabbitMQ service. The application creates, reads from, and writes to a database that uses data that is supplied through the app's web interface.

If you've already created your deployment and just want to connect to your RabbitMQ, you can skip to getting your connection strings and connecting with the RabbitMQ Management Plugin.


Before you begin

Obtain an IBM Cloud account.

You also need to install Node.js and Git.


Step 1. Create a Messages for RabbitMQ service instance

We can create a Messages for RabbitMQ service from the Messages for RabbitMQ page in the IBM Cloud catalog.

Choose a service name, region, organization and space to provision the service in, and for the Select a database version field, choose Latest Preferred Version. In this example, the service name is "example-rabbitmq".

Click Create to provision your service. Provisioning can take a while to complete. You are taken back to your IBM Cloud Dashboard while the service is provisioning.

We can not connect an application to the service until provisioning has completed.


Step 2. Clone the Hello World sample app from GitHub

Clone the Hello World app to your local environment from your terminal by using the following command:

git clone -b node git@github.com:IBM-Cloud/clouddatabases-helloworld-cloudfoundry-examples.git


Step 3. Install the app dependencies

Use npm to install dependencies.

  1. From your terminal, change the directory to where the sample app is located.

  2. Install the dependencies listed in the package.json file.

    npm install


Step 4. Download and install the IBM Cloud CLI tool

The IBM Cloud CLI tool is what you use to communicate with IBM Cloud from your terminal or command line. See Download and install IBM Cloud CLI.


Step 5. Connect to IBM Cloud

  1. Connect to IBM Cloud in the command line tool and follow the prompts to log in.

    ibmcloud login

    If you've a federated user ID, use the ibmcloud login --sso command to log in with your single sign-on ID. See Logging in with a federated ID to learn more.

  2. Make sure that you are targeting the correct IBM Cloud org and space.

    ibmcloud target --cf

    Choose from the options provided, by using the same values that you used when you created the service.


Step 6. Create a Cloud Foundry alias for the database service.

Make the database service discoverable by Cloud Foundry applications by giving it a Cloud Foundry alias.

ibmcloud resource service-alias-create alias-name --instance-name instance-name

The alias name can be the same as the database service instance name. For example, use this command for database that was created in step 1.

ibmcloud resource service-alias-create example-rabbitmq --instance-name example-rabbitmq


Step 7. Update the app's manifest file

IBM Cloud uses a manifest file - manifest.yml to associate an application with a service. Follow these steps to create your manifest file.

  1. In an editor, open a new file and add the following text:

    ---
applications:
- name:    example-helloworld-nodejs
 routes:
 - route: example-helloworld-nodejs.us-south.cf.appdomain.cloud
 memory:  128M
 services:
   - example-rabbitmq

  2. Change the route value to something unique. The route that you choose determines the subdomain of your application's URL: <route>.{region}.cf.appdomain.cloud. Be sure the {region} matches where your application is deployed.

  3. Change the name value. The name that you choose is displayed in your IBM Cloud dashboard.
  4. Update the services value to match the alias of the service you created in Create a Cloud Foundry alias for the database service.


    Step 8. Push the app to IBM Cloud.

This step fails if the service is not finished provisioning from Step 1. We can check its progress on your IBM Cloud Dashboard.

When you push the app, it is automatically bound to the service specified in the manifest file.

ibmcloud cf push


Step 9. Check that the app is connected to your Messages for RabbitMQ service

  1. Go to your Messages for RabbitMQ service dashboard
  2. Select Connections from the dashboard menu. Your application is listed under Connected Applications.

If your application is not listed, repeat Steps 7 and 8, making sure that you entered the correct details in manifest.yml.


Step 10. Use the app

Now, when you visit <route>.{region}.cf.appdomain.cloud/ you can see the contents of your Messages for RabbitMQ collection. As you add words and their definitions, they are added to the database and displayed. If you stop and restart the app, you see any words and definitions that were already added are now listed.


Running the app locally

Instead of pushing the app into IBM Cloud you can run it locally to test the connection to your Messages for RabbitMQ service instance. To connect to the service, you need to create a set of service credentials.

  1. Select Service Credentials from the main menu to open the Service Credentials view.
  2. Click New Credential.
  3. Choose a name for your credentials and click Add.
  4. Your new credentials are now listed. Click View credentials in the corresponding row of the table to view the credentials, and click the Copy icon to copy your credentials.

  5. In your editor of choice, create a new file with the following, inserting your credentials as shown:

    {
 "services": {
   "messages-for-rabbitmq": [
     {
       "credentials": INSERT YOUR CREDENTIALS HERE
     }
   ]
 }
}
  6. Save the file as vcap-local.json in the directory where the sample app is located.

To avoid accidentally exposing your credentials when you push an application to GitHub or IBM Cloud, make sure that the file that contains your credentials is listed in the relevant ignore file. If you open .cfignore and .gitignore in your application directory, you can see that vcap-local.json is listed in both. It is not included in the files that are uploaded when you push the app to either GitHub or IBM Cloud.

Now start the local server.

npm start

The app is now running at http://localhost:8080. We can add words and definitions to your Messages for RabbitMQ database. When you stop and restart the app, any words you added are displayed when you refresh the page.


Next steps

To understand more about how the sample app works, you can read the application's readme file, or the code comments in server.js, which give some information about the app's functions.

To start exploring your Messages for RabbitMQ service, see the following topics about the service dashboard: