Working with user-provided services and the Liberty starter app

You can bind your applications in Cloud Foundry Enterprise Environment to services that exist outside of your Cloud Foundry Enterprise Environment 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 Liberty for Java™ getting started application.

Before you begin

You need the following accounts and tools:

Access to Cloud Foundry Enterprise Environment
IBM Cloud account
Cloud Foundry CLI
Git
Maven

Step 1: Clone the sample app

First, clone the sample app GitHub repo.

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

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

Use Maven to build your source code and run the app.

On the command line, change the directory to where the sample app is located.
```
cd get-started-java
```
Use Maven to install dependencies and build the .war file.
```
mvn clean install
```
Run the app locally on Liberty.
```
mvn install liberty:run-server
```

When you see the message, The server defaultServer is ready to run a smarter planet, you can view your app at: http://localhost:9080/GetStartedJava.

To stop your app, press Ctrl-C in the command line window where you started the app.

Step 3: Prepare the app for deployment

To deploy 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-java directory.

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

applications:
 - name: GetStartedJava
   random-route: true
   path: target/GetStartedJava.war
   memory: 512M
   instances: 1

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 Cloud Foundry Enterprise Environment

Deploy your app to your Cloud Foundry Enterprise Environment instance by using your Cloud Foundry Enterprise Environment URL.
```
cf api <API endpoint of Cloud Foundry Enterprise Environment>
```
Log in to your Cloud Foundry Enterprise Environment account.
```
cf login
```
From within the get-started-java 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 that is 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: Create a Cloudant NoSQL DB service instance

Next, you add a Cloudant NoSQL DB database on IBM Cloud to this 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 Cloud Foundry Enterprise Environment.

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.

Save your Cloudant NoSQL DB credentials in a JSON file.

{
 "username": "<username>",
 "password": "<password>",
 "host": "<host.dns.name>",
 "port": <port>,
 "url": "https://<username>:<password>@<host.dns.name>"
}

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.
```
cf create-user-provided-service <Your-Service-Name> -p <path to json file>
```

Step 6: Use Cloudant NoSQL DB

Bind the user-provided service to the getting started application.
```
cf bs <Your-App-Name> <Your-Service-Name>
```
Restage the application.
```
cf restage <Your-App-Name>
```

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.

Step 7: Use Cloudant NoSQL DB locally

Next, you update your local code to point to this database. You can store the credentials for the services in a properties file. This file is used only when the application is running locally. When you run the application in Cloud Foundry Enterprise Environment, the credentials are read from the VCAP_SERVICES environment variable.

Open the src/main/resources/cloudant.properties file:
```
cloudant_url=
```
Copy and paste the value of the url from the Service credentials, which you saved in a file in Step 5, to the url field of the cloudant.properties file. Save the changes.
```
cloudant_url=https://123456789 ... bluemix.cloudant.com
```
Stop the local Liberty server and then, from within the get-started-java directory, restart it with the following command:
```
mvn install liberty:run-server
```

Step 8: Confirm

Refresh your browser view at http://localhost:9080/GetStartedJava/. Any names that you enter in the app are added to the database.

Your local app and the Cloud Foundry Enterprise Environment app share the Cloudant NoSQL DB database. Names that you add from either app appear in both when you refresh the browsers.