Getting Started

Before you begin

• You need an IBM Cloud account.
• Install Node.js and Git.
• See Getting to production for guidance on setting up a basic IBM Cloud® Messages for RabbitMQ deployment.

Create a Messages for RabbitMQ service instance

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.

You cannot connect an application to the service until provisioning is complete.

Clone the Hello World sample app from GitHub

Use the following command to clone the Hello World app to your local environment from your terminal:

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

Install the app dependencies

Use npm to install dependencies.

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

Install the dependencies listed in the package.json file.

npm install

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. For more information, see Download and install IBM Cloud CLI.

Connect to IBM Cloud

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

ibmcloud login

If you have 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.

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

ibmcloud target --cf

By using the same values that you used when creating the service, choose from the provided options.

Create a Cloud Foundry alias for the database service

IBM® Cloud Foundry is deprecated. As of 30 November 2022 new IBM® Cloud Foundry applications cannot be created and only existing users will be able to deploy applications. End-of-support happens on 1 June 2023. Any instances that still exist on 1 June 2023 will be deleted. For more information, see Deprecation of IBM Cloud Foundry.

Make the database service discoverable by IBM® Cloud Foundry applications by giving it a IBM® 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

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.

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

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.

Change the name value. The name that you choose is displayed in your IBM Cloud dashboard.

Update the services value to match the alias of the service you created in Create a Cloud Foundry alias for the database service.

Push the app to IBM Cloud.

If the service is not finished provisioning from Step 1, this step fails. You 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

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

Go to your Messages for RabbitMQ service dashboard

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.

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.

• Select Service credentials from the main menu to open the Service Credentials view.
• Click New credential.
• Choose a name for your credentials and click Add.
• 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.
• 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
      }
    ]
  }
}

• 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. You 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

Check out Best Practices for RabbitMQ on the IBM Cloud.

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:

• Dashboard overview
• Backups
• Creating users and getting connection strings