Working with user-provided services and the Node.js starter app

You can bind your applications in IBM® Cloud Private Cloud Foundry to services that exist outside of your IBM Cloud Private Cloud Foundry environment.

Cloud Foundry gives a mechanism to connect services and applications that might not be provided by or available within your cloud instance. To learn more about Cloud Foundry capabilities, see User-provided services External link icon .

This example uses a Cloudant® NoSQL DB instance and guides you through the process to prepare and deploy your application, create a user-provided service, and connect to a Cloudant database by using the Node.js getting started application.

Before you begin

You need the following accounts and tools:

Access to the IBM Cloud Private Cloud Foundry environment
IBM Cloud account
Cloud Foundry CLI
Git
Node.js

Prepare and deploy your application

Step 1: Clone the sample app

First, clone the sample app GitHub repo.

  git clone https://github.com/IBM-Bluemix/get-started-node

Step 2: Run the app locally by using the command line

On the command line, change the directory to where the sample app is located.
```
cd get-started-node
```
Install the dependencies that are listed in the package.json file to run the app locally.
```
npm install
```
Run the app.
```
npm start
```

You can view your app at http://localhost:3000.

Tip: Use nodemon External link icon for automatic restarting of application with file changes.

Step 3: Prepare the app for deployment

To deploy your application to IBM Cloud Private, it can be helpful to set up a manifest.yml file. The manifest.yml file includes basic information about your app, such as the name, how much memory to allocate for each instance, and the route. You can find a sample manifest.yml file in the get-started-node directory.

Open the manifest.yml file, and change the name from GetStartedNode to your app name, <var class="keyword varname" data-hd-keyref="app_name">app_name</var>.

applications:
- name: GetStartedNode
  random-route: true
  memory: 128M

Tip: In this manifest.yml file, random-route: true generates a random route for your app to prevent your route from colliding with others. If you choose to, you can replace random-route: true with host: myChosenHostName, and supply a host name of your choice.

Step 4: Deploy to IBM Cloud Private Cloud Foundry

Deploy your app to your IBM Cloud Private Cloud Foundry by using your IBM Cloud Private Cloud Foundry URL.
```
cf api <url of IBM Cloud Private Cloud Foundry>
```
Log in to your IBM Cloud Private Cloud Foundry account.
```
cf login
```
From within the get-started-node directory, push your application to IBM Cloud Private.
```
cf push
```
Deploying your application can take a few minutes. When deployment completes, you see a message that your app is running. View your app at the URL listed in the output of the push command, or view both the app deployment status and the URL by running the following command:
```
cf apps
```

Tip: You can troubleshoot errors in the deployment process by using the cf logs <Your-App-Name> --recent command.

Step 5: Add a database

Next, you add a Cloudant NoSQL DB database on IBM Cloud to your application and set up the application to run locally and on IBM Cloud Private. You need to create the Cloudant database on IBM Cloud. Then, you bind your starter application to the IBM Cloud service from within IBM Cloud Private Cloud Foundry.

In your browser, log in to IBM Cloud and go to the Catalog.
In the Data & Analytics section, select Cloudant NoSQL DB and then create the service.
Go to Service credentials and view the credentials for the service.
After the Cloudant instance is created, you must save the credentials to bind your application to it. Save your Cloudant NoSQL DB credentials in a JSON file, with a file name such as cloudant_credentials.json.
```
{
 "username": "<username>",
 "password": "<password>",
 "host": "<host.dns.name>",
 "port": <port>,
 "url": "https://<username>:<password>@<host.dns.name>"
}
```

Optional: Run the application locally

To run the application locally, you need to update your local code to point to this database. Create a JSON file to store the credentials for the services the application uses. This file is used only when the application is running locally. When the application is running in the cloud, the credentials are read from the VCAP_SERVICES environment variable.

Tip: This vcap-local.json JSON file is not the same as your cloudant-credentials.json file. The vcap-local.json file is used only to run your application locally.

In the get-started-node directory, create a file that is called vcap-local.json with the following content:
```
{
 "services": {
   "cloudantNoSQLDB": [
     {
       "credentials": {
         "url":"CLOUDANT_DATABASE_URL"
       },
       "label": "cloudantNoSQLDB"
     }
   ]
 }
}
```
Tip: You can use environment variables to separate deployment settings from your source code. For example, instead of hardcoding a database password, you can store it in an environment variable that you reference in your source code.
From the cloudant-credentials.json file you saved in step 5, or from the Service credentials in step 5, copy and paste just the url from the credentials to the url field of the vcap-local.json file, replacing CLOUDANT_DATABASE_URL.
Stop your local application and then restart it.
```
npm start
```
View your local app at http://localhost:3000. Any names that you enter in the app are added to the database.

Tip: IBM Cloud defines the PORT environment variable when your app runs on the cloud. When you run your app locally, the PORT environment variable is not defined, so 3000 is used as the port number. For more information about running applications locally, see Run your app locally.

Step 6: Create a user-provided service

To work with the getting started application, you must include cloudant in the service name of the user-provided service that you create. The getting started application parses the VCAP services variable and looks for a user-provided service with a name that contains cloudant, such as my-cloudantNoSQLDB-ups.

Use the create-user-provided-service command to create the user-provided service. Specify the service name and the path to the cloudant-credentials.json file that you created in step 5.

cf create-user-provided-service <service name> -p <path to json file>

Step 7: Bind the user-provided service and restage the app

Bind the user-provided service to the getting started application, and then restage it.

cf bs <Your-App-Name> <Your-Service-Name>
cf restage <Your-App-Name>

Step 8: Confirm

Browse to your application and confirm that you can add multiple names to the name field of your starter application.

Your local app and the IBM Cloud Private Cloud Foundry application share the Cloudant database. Names that you add from either app appear in both when you refresh the browsers.