[[cloudfoundry]]
== Pivotal CloudFoundry
:geode-name: {apache-geode-name}
:images-dir: ./images
:pcc-name: Pivotal Cloud Cache
:pcf-name: Pivotal CloudFoundry


NOTE: As of the VMware, Inc. acquisition of Pivotal Software, Inc., {pcf-name} (PCF) is now known as VMware Tanzu
Application Service (TAS) for VMs. Also, {pcc-name} (PCC) has been rebranded as VMware Tanzu GemFire for VMS.
This documentation will eventually be updated to reflect the rebranding.

In most cases, when you deploy (that is, `cf push`) your Spring Boot applications to {pcf-name} (PCF), you bind
your application to one or more instances of the {pcc-name} (PCC) service.

In a nutshell, {pivotal-cloudcache-website}[{pcc-name}] (PCC) is a managed version of
{pivotal-gemfire-website}[{pivotal-gemfire-name}] that runs in {pivotal-cloudfoundry-website}[{pcf-name}] (PCF).
When running in or across cloud environments (such as AWS, Azure, GCP, or PWS), PCC with PCF offers several advantages
over trying to run and manage your own standalone {geode-name} clusters. It handles many of the infrastructure-related,
operational concerns so that you need not do so.

[[cloudfoundry-cloudcache-security-auth-runtime-user-configuration]]
=== Running a Spring Boot application as a specific user

By default, Spring Boot applications run as a `cluster_operator` role-based user in {pcf-name} when the application
is bound to a {pcc-name} service instance.

A `cluster_operator` has full system privileges (that is, authorization) to do whatever that user wishes to involving
the PCC service instance. A `cluster_operator` has read and write access to all the data, can modify the schema (for
example, create and destroy Regions, add and remove Indexes, change eviction or expiration policies, and so on), start
and stop servers in the PCC cluster, or even modify permissions.

.About cluster_operator as the default user
****
One of the reasons why Spring Boot applications default to running as a `cluster_operator` is to allow configuration
metadata to be sent from the client to the server. Enabling configuration metadata to be sent from the client to the
server is a useful development-time feature and is as simple as annotating your main `@SpringBootApplication` class
with the `@EnableClusterConfiguration` annotation:

.Using `@EnableClusterConfiguration`
====
[source,java]
----
@SpringBootApplication
@EnableClusterConfiguration(useHttp = true)
class SpringBootApacheGeodeClientCacheApplication {  }
----
====

With `@EnableClusterConfiguration`, Region and OQL Index configuration metadata that is defined on the client can be
sent to servers in the PCC cluster. {geode-name} requires matching Regions by name on both the client and the servers
in order for clients to send and receive data to and from the cluster.

For example, when you declare the Region where an application entity is persisted by using the `@Region` mapping
annotation and declare the `@EnableEntityDefinedRegions` annotation on the main `@SpringBootApplication` class
in conjunction with the `@EnableClusterConfiguration` annotation, not only does SBDG create the required client Region,
but it also sends the configuration metadata for this Region to the servers in the cluster to create the matching,
required server Region, where the data for your application entity is managed.
****

However...

> With great power comes great responsibility. - Uncle Ben

Not all Spring Boot applications using PCC need to change the schema or even modify data. Rather, certain applications
may need only read access. Therefore, it is ideal to be able to configure your Spring Boot applications to run with
a different user at runtime other than the auto-configured `cluster_operator`, by default.

A prerequisite for running a Spring Boot application in PCC with a specific user is to create a user with restricted
permissions by using {pcf-name} AppsManager while provisioning the PCC service instance to which the Spring Boot
application is bound.

Configuration metadata for the PCC service instance might appear as follows:

.{pcc-name} configuration metadata
====
[source,json]
----
{
  "p-cloudcache":[{
    "credentials": {
      "distributed_system_id": "0",
      "locators": [ "localhost[55221]" ],
      "urls": {
        "gfsh": "https://cloudcache-12345.services.cf.pws.com/gemfire/v1",
        "pulse": "https://cloudcache-12345.services.cf.pws.com/pulse"
      },
      "users": [{
        "password": "*****",
        "roles": [ "cluster_operator" ],
        "username": "cluster_operator_user"
      }, {
        "password": "*****",
        "roles": [ "developer" ],
        "username": "developer_user"
      }, {
        "password": "*****",
        "roles": [ "read-only-user" ],
        "username": "guest"
      }],
      "wan": {
        "sender_credentials": {
          "active": {
            "password": "*****",
            "username": "gateway-sender-user"
          }
        }
      }
    },
    "name": "jblum-pcc",
    "plan": "small",
    "tags": [ "gemfire", "cloudcache", "database", "pivotal" ]
  }]
}
----
====

In the PCC service instance configuration metadata shown in the preceding example, we see a `guest` user with
the `read-only-user` role. If the `read-only-user` role is properly configured with read-only permissions as the name
implies, we could configure our Spring Boot application to run as `guest` with read-only access:

.Configuring a Spring Boot application to run as a specific user
====
[source,properties]
----
# Spring Boot application.properties for PCF when using PCC

spring.data.gemfire.security.username=guest
----
====

TIP: The `spring.data.gemfire.security.username` property corresponds directly to the SDG `@EnableSecurity` annotation's
`securityUsername` attribute. See the
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html#securityUsername--[Javadoc]
for more details.

The `spring.data.gemfire.security.username` property is the same property used by Spring Data for {geode-name} (SDG) to
configure the runtime user of your Spring Data application when you connect to an externally managed {geode-name}
cluster.

In this case, SBDG uses the configured username to look up the authentication credentials of the user to set
the username and password used by the Spring Boot `ClientCache` application when connecting to PCC while running in PCF.

If the username is not valid, an `IllegalStateException` is thrown.

By using {spring-boot-docs-html}/#boot-features-profiles[Spring profiles], it would be a simple matter to configure
the Spring Boot application to run with a different user depending on environment.

See the {pcc-name} documentation on {pivotal-cloudcache-docs}/security.html[security] for configuring users with
assigned roles and permissions.

[[cloudfoundry-cloudcache-security-auth-autoconfiguration-override]]
==== Overriding Authentication Auto-configuration

It should be understood that auto-configuration for client authentication is available only for managed environments,
such as {pcf-name}. When running in externally managed environments, you must explicitly set a username and password
to authenticate, as described in <<geode-security-auth-clients-non-managed>>.

To completely override the auto-configuration of client authentication, you can set both a username and a password:

.Overriding Security Authentication Auto-configuration with explicit username and password
====
[source,txt]
----
# Spring Boot application.properties

spring.data.gemfire.security.username=MyUser
spring.data.gemfire.security.password=MyPassword
----
====

In this case, SBDG's auto-configuration for authentication is effectively disabled and security credentials are not
extracted from the environment.

[[cloudfoundry-cloudcache-serviceinstance-targeting]]
=== Targeting Specific {pcc-name} Service Instances

It is possible to provision multiple instances of the {pcc-name} service in your {pcf-name} environment. You can then
bind multiple PCC service instances to your Spring Boot application.

However, Spring Boot for {geode-name} (SBDG) only auto-configures one PCC service instance for your Spring Boot
application. This does not mean that it is not possible to use multiple PCC service instances with your Spring Boot
application, just that SBDG only auto-configures one service instance for you.

You must select which PCC service instance your Spring Boot application automatically auto-configures for you when
you have multiple instances and want to target a specific PCC service instance to use.

To do so, declare the following SBDG property in Spring Boot `application.properties`:

.Spring Boot application.properties targeting a specific PCC service instance by name
====
[source,properties]
----
# Spring Boot application.properties

spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name=pccServiceInstanceTwo
----
====

The `spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name` property tells SBDG which PCC service instance
to auto-configure.

If the PCC service instance identified by the property does not exist, SBDG throws an `IllegalStateException`
stating the PCC service instance by name could not be found.

If you did not set the property and your Spring Boot application is bound to multiple PCC service instances,
SBDG auto-configures the first PCC service instance it finds by name, alphabetically.

If you did not set the property and no PCC service instance is found, SBDG logs a warning.

[[cloudfoundry-cloudcache-multiinstance-using]]
=== Using Multiple {pcc-name} Service Instances

If you want to use multiple PCC service instances with your Spring Boot application, you need to configure multiple
connection `Pools` connected to each PCC service instance used by your Spring Boot application.

The configuration would be similar to the following:

.Multiple {pcc-name} Service Instance Configuration
====
[source,java]
----
@Configuration
@EnablePools(pools = {
  @EnablePool(name = "PccOne"),
  @EnablePool(name = "PccTwo"),
  ...,
  @EnablePool(name = "PccN")
})
class PccConfiguration {
  // ...
}
----
====

You would then externalize the configuration for the individually declared `Pools` in Spring Boot
`application.properties`:

.Configuring Locator-based Pool connections
====
[source,properties]
----
# Spring Boot `application.properties`

spring.data.gemfire.pool.pccone.locators=pccOneHost1[port1], pccOneHost2[port2], ..., pccOneHostN[portN]

spring.data.gemfire.pool.pcctwo.locators=pccTwoHost1[port1], pccTwoHost2[port2], ..., pccTwoHostN[portN]
----
====

NOTE: Though less common, you can also configure the `Pool` of connections to target specific servers in the cluster
by setting the `spring.data.gemfire.pool.<named-pool>.severs` property.

TIP: Keep in mind that properties in Spring Boot `application.properties` can refer to other properties:
`property=$\{otherProperty}`. This lets you further externalize properties by using Java System properties
or environment variables.

A client Region is then assigned the Pool of connections that are used to send data to and from the specific
PCC service instance (cluster):

.Assigning a Pool to a client Region
====
[source,java]
----
@Configuration
class GeodeConfiguration {

  @Bean("Example")
  ClientRegionFactoryBean exampleRegion(GemFireCache gemfireCache,
      @Qualifier("PccTwo") Pool poolForPccTwo) {

    ClientRegionFactoryBean exampleRegion = new ClientRegionFactoryBean();

    exampleRegion.setCache(gemfireCache);
    exampleRegion.setPool(poolForPccTwo);
    exampleRegion.setShortcut(ClientRegionShortcut.PROXY);

    return exampleRegion;
  }
}
----
====

You can configure as many Pools and client Regions as your application needs. Again, the `Pool` determines
the {pcc-name} service instance and cluster in which the data for the client Region resides.

NOTE: By default, SBDG configures all `Pools` declared in a Spring Boot `ClientCache` application to connect to
and use a single PCC service instance. This may be a targeted PCC service instance when you use the
`spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name` property
as discussed <<cloudfoundry-cloudcache-multiinstance-using,earlier>>.

[[cloudfoundry-geode]]
=== Hybrid {pcf-name} and {geode-name} Spring Boot Applications

Sometimes, it is desirable to deploy (that is, `cf push`) and run your Spring Boot applications in {pcf-name}
but still connect your Spring Boot applications to an externally managed, standalone {geode-name} cluster.

Spring Boot for {geode-name} (SBDG) makes this a non-event and honors its "_little to no code or configuration changes
necessary_" goal. Regardless of your runtime choice, it should just work!

To help guide you through this process, we cover the following topics:

. Install and Run PCFDev.
. Start an {geode-name} cluster.
. Create a User-Provided Service (CUPS).
. Push and Bind a Spring Boot application.
. Run the Spring Boot application.

[[cloudfoundry-geode-pcfdev]]
==== Running PCFDev

For this exercise, we use https://docs.pivotal.io/pcf-dev/install-osx.html[PCF Dev].

PCF Dev, much like PCF, is an elastic application runtime for deploying, running, and managing your Spring Boot
applications. However, it does so in the confines of your local development environment -- that is, your workstation.

Additionally, PCF Dev provides several services, such as MySQL, Redis, and RabbitMQ. You Spring Boot application
can bind to and use these services to accomplish its tasks.

However, PCF Dev lacks the {pcc-name} service that is available in PCF. This is actually ideal for this exercise since
we are trying to build and run Spring Boot applications in a PCF environment but connect to an externally managed,
standalone {geode-name} cluster.

As a prerequisite, you need to follow the steps outlined in the
https://pivotal.io/platform/pcf-tutorials/getting-started-with-pivotal-cloud-foundry-dev/introduction[tutorial]
to get PCF Dev set up and running on your workstation.

To run PCF Dev, execute the following `cf` CLI command, replacing the path to the TGZ file with the file you acquired
from the https://network.pivotal.io/products/pcfdev[download]:

.Start PCF Dev
====
[source,txt]
----
$ cf dev start -f ~/Downloads/Pivotal/CloudFoundry/Dev/pcfdev-v1.2.0-darwin.tgz
----
====

You should see output similar to the following:

.Running PCF Dev
====
[source,txt]
----
Downloading Network Helper...
Progress: |====================>| 100.0%
Installing cfdevd network helper (requires administrator privileges)...
Password:
Setting up IP aliases for the BOSH Director & CF Router (requires administrator privileges)
Downloading Resources...
Progress: |====================>| 100.0%
Setting State...
WARNING: PCF Dev requires 8192 MB of RAM to run. This machine may not have enough free RAM.
Creating the VM...
Starting VPNKit...
Waiting for the VM...
Deploying the BOSH Director...

Deploying PAS...
  Done (14m34s)
Deploying Apps-Manager...
  Done (1m41s)

 	 ██████╗  ██████╗███████╗██████╗ ███████╗██╗   ██╗
 	 ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔════╝██║   ██║
 	 ██████╔╝██║     █████╗  ██║  ██║█████╗  ██║   ██║
 	 ██╔═══╝ ██║     ██╔══╝  ██║  ██║██╔══╝  ╚██╗ ██╔╝
 	 ██║     ╚██████╗██║     ██████╔╝███████╗ ╚████╔╝
 	 ╚═╝      ╚═════╝╚═╝     ╚═════╝ ╚══════╝  ╚═══╝
 	             is now running!

 	To begin using PCF Dev, please run:
 	    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation

 	Admin user => Email: admin / Password: admin
 	Regular user => Email: user / Password: pass

 	To access Apps Manager, navigate here: https://apps.dev.cfdev.sh

 	To deploy a particular service, please run:
 	    cf dev deploy-service <service-name> [Available services: mysql,redis,rabbitmq,scs]
----
====

To use the `cf` CLI tool, you must login to the PCF Dev environment:

.Login to PCF Dev using `cf` CLI
====
[source,txt]
----
$ cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
----
====

You can also access the https://apps.dev.cfdev.sh/[PCF Dev Apps Manager] tool from your Web browser at the following URL:

https://apps.dev.cfdev.sh/

Apps Manager provides a nice UI to manage your org, space, services and apps. It lets you push and update apps,
create services, bind apps to the services, and start and stop your deployed applications, among many other things.

[[cloudfoundry-geode-cluster]]
==== Running an {geode-name} Cluster

Now that PCF Dev is set up and running, you need to start an external, standalone {geode-name} cluster to which our
Spring Boot application connects and uses to manage its data.

You need to install a {apache-geode-website}/releases/[distribution] of {geode-name} on your computer. Then you must
set the `$GEODE` environment variable. It is also convenient to add `$GEODE/bin` to your system `$PATH`.

Afterward, you can launch the Geode Shell (_Gfsh_) tool:

.Running Gfsh
====
[source,txt]
----
$ echo $GEODE
/Users/jblum/pivdev/apache-geode-1.6.0

$ gfsh
    _________________________     __
   / _____/ ______/ ______/ /____/ /
  / /  __/ /___  /_____  / _____  /
 / /__/ / ____/  _____/ / /    / /
/______/_/      /______/_/    /_/    1.6.0

Monitor and Manage Apache Geode
gfsh>
----
====

We have provided the Gfsh shell script that you can use to start the {geode-name} cluster:

.Gfsh shell script to start the {geode-name} cluster
====
[source,txt]
----
include::{docs-resources-dir}/geode/bin/start-cluster.gfsh[]
----
====

The `start-cluster.gfsh` shell script starts one Geode Locator and one Geode server.

A Locator is used by clients to discover and connect to servers in a cluster to manage its data. A Locator is also used
by new servers that join a cluster as peer members, which lets the cluster be elastically scaled out (or scaled down,
as needed). A Geode server stores the data for the application.

You can start as many Locators or servers as necessary to meet the availability and load demands of your application.
The more Locators and servers your cluster has, the more resilient it is to failure. However, you should size your
cluster accordingly, based on your application's needs, since there is overhead relative to the cluster size.

You see output similar to the following when starting the Locator and server:

.Starting the {geode-name} cluster
====
[source,txt]
----
gfsh>start locator --name=LocatorOne --log-level=config --classpath=/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar --J=-Dgemfire.security-manager=org.springframework.geode.security.TestSecurityManager --J=-Dgemfire.http-service-port=8080
Starting a Geode Locator in /Users/jblum/pivdev/lab/LocatorOne...
..
Locator in /Users/jblum/pivdev/lab/LocatorOne on 10.99.199.24[10334] as LocatorOne is currently online.
Process ID: 14358
Uptime: 1 minute 1 second
Geode Version: 1.6.0
Java Version: 1.8.0_192
Log File: /Users/jblum/pivdev/lab/LocatorOne/LocatorOne.log
JVM Arguments: -Dgemfire.enable-cluster-configuration=true -Dgemfire.load-cluster-configuration-from-dir=false -Dgemfire.log-level=config -Dgemfire.security-manager=org.springframework.geode.security.TestSecurityManager -Dgemfire.http-service-port=8080 -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-core-1.6.0.jar:/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar:/Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-dependencies.jar

Security Manager is enabled - unable to auto-connect. Please use "connect --locator=10.99.199.24[10334] --user --password" to connect Gfsh to the locator.

Authentication required to connect to the Manager.

gfsh>connect
Connecting to Locator at [host=localhost, port=10334] ..
Connecting to Manager at [host=10.99.199.24, port=1099] ..
user: admin
password: *****
Successfully connected to: [host=10.99.199.24, port=1099]

gfsh>start server --name=ServerOne --log-level=config --user=admin --password=admin --classpath=/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar
Starting a Geode Server in /Users/jblum/pivdev/lab/ServerOne...
....
Server in /Users/jblum/pivdev/lab/ServerOne on 10.99.199.24[40404] as ServerOne is currently online.
Process ID: 14401
Uptime: 3 seconds
Geode Version: 1.6.0
Java Version: 1.8.0_192
Log File: /Users/jblum/pivdev/lab/ServerOne/ServerOne.log
JVM Arguments: -Dgemfire.default.locators=10.99.199.24[10334] -Dgemfire.security-username=admin -Dgemfire.start-dev-rest-api=false -Dgemfire.security-password=******** -Dgemfire.use-cluster-configuration=true -Dgemfire.log-level=config -XX:OnOutOfMemoryError=kill -KILL %p -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-core-1.6.0.jar:/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar:/Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-dependencies.jar
----
====

Once the cluster has been started successfully, you can list the members:

.List members of the cluster
====
[source,txt]
----
gfsh>list members
   Name    | Id
---------- | -----------------------------------------------------------------
LocatorOne | 10.99.199.24(LocatorOne:14358:locator)<ec><v0>:1024 [Coordinator]
ServerOne  | 10.99.199.24(ServerOne:14401)<v1>:1025
----
====

Currently, we have not defined any Regions in which to store our application's data:

.No Application Regions
====
[source,txt]
----
gfsh>list regions
No Regions Found
----
====

This is deliberate, since we are going to let the application drive its schema structure, both on the client
(application) as well as on the server-side (cluster). We cover this in more detail later in this chapter.

[[cloudfoundry-geode-cups]]
==== Creating a User-Provided Service

Now that we have PCF Dev and a small {geode-name} cluster up and running, it is time to create a user-provided service
to the external, standalone {geode-name} cluster that we started in <<cloudfoundry-geode-cluster,step 2>>.

As mentioned, PCF Dev offers MySQL, Redis and RabbitMQ services (among others). However, to use {geode-name} in the same
capacity as you would {pcc-name} when running in a production-grade PCF environment, you need to create a user-provided
service for the standalone {geode-name} cluster.

To do so, run the following `cf` CLI command:

.cf cups command
====
[source,txt]
----
$ cf cups <service-name> -t "gemfire, cloudcache, database, pivotal" -p '<service-credentials-in-json>'
----
====

NOTE: It is important that you specify the tags (`gemfire`, `cloudcache`, `database`, `pivotal`) exactly as shown
in the preceding `cf` CLI command.

The argument passed to the `-p` command-line option is a JSON document (object) containing the credentials for our
user-provided service.

The JSON object is as follows:

.User-Provided Service Crendentials JSON
====
[source,json]
----
{
	"locators": [ "<hostname>[<port>]" ],
	"urls": { "gfsh": "https://<hostname>/gemfire/v1" },
	"users": [{ "password": "<password>", "roles": [ "cluster_operator" ], "username": "<username>" }]
}
----
====

The complete `cf` CLI command would be similar to the following:

.Example `cf cups` command
====
[source,txt]
----
cf cups apacheGeodeService -t "gemfire, cloudcache, database, pivotal" \
  -p '{ "locators": [ "10.99.199.24[10334]" ], "urls": { "gfsh": "https://10.99.199.24/gemfire/v1" }, "users": [{ "password": "admin", "roles": [ "cluster_operator" ], "username": "admin" }] }'
----
====

We replaced the `<hostname>` placeholder with the IP address of our standalone {geode-name} Locator. You can find
the IP address in the Gfsh `start locator` command output shown in the preceding example.

Additionally, the `<port>` placeholder has been replaced with the default Locator port, `10334`,

Finally, we set the `username` and `password` accordingly.

TIP: Spring Boot for {geode-name} (SBDG) provides template files in the `{docs-dir}/src/main/resources` directory.

Once the service has been created, you can query the details of the service from the `cf` CLI:

.Query the CF Dev Services
====
[source,txt]
----
$ cf services
Getting services in org cfdev-org / space cfdev-space as admin...

name                 service         plan   bound apps      last operation   broker
apacheGeodeService   user-provided          boot-pcc-demo


$ cf service apacheGeodeService
Showing info of service apacheGeodeService in org cfdev-org / space cfdev-space as admin...

name:      apacheGeodeService
service:   user-provided
tags:      gemfire, cloudcache, database, pivotal

bound apps:
name            binding name   status             message
boot-pcc-demo                  create succeeded
----
====

You can also view the "apacheGeodeService" from Apps Manager, starting from the `Service` tab in your org and space:

image::{images-dir}/pcfdev-appsmanager-org-space-services.png[]

By clicking on the "apacheGeodeService" service entry in the table, you can get all the service details, such as
the bound apps:

image::{images-dir}/pcfdev-appsmanager-org-space-service-boundapps.png[]

You can also view and set the configuration:

image::{images-dir}/pcfdev-appsmanager-org-space-service-configuration.png[]

This brief section did not cover all the capabilities of the Apps Manager. We suggest you explore its UI to see all
that is possible.

TIP: You can learn more about CUPS in the
{pivotal-cloudfoundry-docs}/devguide/services/user-provided.html[PCF documentation].

[[cloudfoundry-geode-app]]
==== Push and Bind a Spring Boot application

Now it is time to push a Spring Boot application to PCF Dev and bind the application to the `apacheGeodeService`.

Any Spring Boot `ClientCache` application that uses SBDG works for this purpose. For this example, we use the
https://github.com/jxblum/PCCDemo/tree/sbdg-doc-ref[PCCDemo] application, which is available in GitHub.

After cloning the project to your computer, you must run a build to produce the artifact to push to PCF Dev:

.Build the PCCDemo application
====
[source,txt]
----
$ mvn clean package
----
====

Then you can push the application to PCF Dev with the following `cf` CLI command:

.Push the application to PCF Dev
====
[source,txt]
----
$ cf push boot-pcc-demo -u none --no-start -p target/client-0.0.1-SNAPSHOT.jar
----
====

Once the application has been successfully deployed to PCF Dev, you can get the application details:

.Get details for the deployed application
====
[source,txt]
----
$ cf apps
Getting apps in org cfdev-org / space cfdev-space as admin...
OK

name            requested state   instances   memory   disk   urls
boot-pcc-demo   stopped           0/1         768M     1G     boot-pcc-demo.dev.cfdev.sh


$ cf app boot-pcc-demo
Showing health and status for app boot-pcc-demo in org cfdev-org / space cfdev-space as admin...

name:              boot-pcc-demo
requested state:   stopped
routes:            boot-pcc-demo.dev.cfdev.sh
last uploaded:     Tue 02 Jul 00:34:09 PDT 2019
stack:             cflinuxfs3
buildpacks:        https://github.com/cloudfoundry/java-buildpack.git

type:           web
instances:      0/1
memory usage:   768M
     state   since                  cpu    memory   disk     details
#0   down    2019-07-02T21:48:25Z   0.0%   0 of 0   0 of 0

type:           task
instances:      0/0
memory usage:   256M

There are no running instances of this process.
----
====

You can bind the PPCDemo application to the `apacheGeodeService` using the `cf` CLI command:

.Bind application to `apacheGeodeService` using CLI
====
[source,txt]
----
cf bind-service boot-pcc-demo apacheGeodeService
----
====

Alternatively, you can create a YAML file (`manifest.yml` in `src/main/resources`) that contains
the deployment descriptor:

.Example YAML deployment descriptor
====
[source,yml]
----
\---
applications:
  - name: boot-pcc-demo
    memory: 768M
    instances: 1
    path: ./target/client-0.0.1-SNAPSHOT.jar
    services:
      - apacheGeodeService
    buildpacks:
      - https://github.com/cloudfoundry/java-buildpack.git
----
====

You can also use Apps Manager to view application details and bind and unbind additional services.
Start by navigating to the `App` tab under your org and space:

image::{images-dir}/pcfdev-appsmanager-org-space-apps.png[]

From there, you can click on the desired application and navigate to the `Overview`:

image::{images-dir}/pcfdev-appsmanager-org-space-app-overview.png[]

You can also review the application `Settings`. Specifically, we are looking at the configuration of the applicatinon
once it is bound to the `apacheGeodeService`, as seen in the `VCAP_SERVICES` environment variable:

image::{images-dir}/pcfdev-appsmanager-org-space-app-settings-envvars.png[]

This JSON document structure is not unlike the configuration used to bind your Spring Boot `ClientCache` application
to the {pcc-name} service when deploying the same application to {pcf-name}. This is actually key if you want to
minimize the amount of boilerplate code and configuration changes when you migrate between different CloudFoundry
environments, even https://www.cloudfoundry.org/[Open Source CloudFoundry].

Again, SBDG's goal is to simply the effort for you to build, run, and manage your application, in whatever context
your application lands, even if it changes later. If you follow the steps in this documentation, you can realize
that goal.

[[cloudfoundry-geode-app-run]]
==== Running the Spring Boot application

All that is left to do now is run the application.

You can start the PCCDemo application from the `cf` CLI by using the following command:

.Start the Spring Boot application
====
[source,txt]
----
$ cf start boot-pcc-demo
----
====

Alternatively, you can also start the application from Apps Manager. This is convenient, since you can then tail
and monitor the application log file.

image::{images-dir}/pcfdev-appsmanager-org-space-app-logs.png[]

Once the application has started, you can click the https://boot-pcc-demo.dev.cfdev.sh/[VIEW APP] link
in the upper right corner of the `APP` screen.

image::{images-dir}/PCCDemo-app-screenshot.png[]

You can navigate to any of the application Web Service, Controller endpoints.  For example, if you know the ISBN
of a book, you can access it from your Web browser:

image::{images-dir}/PCCDemo-app-book-by-isbn-screenshot.png[]

You can also access the same data from the Gfsh command-line tool. However, the first thing to observe is that our
application informed the cluster that it needed a Region called `Books`:

.Books Region
====
[source,txt]
----
gfsh>list regions
List of regions
---------------
Books


gfsh>describe region --name=/Books
..........................................................
Name            : Books
Data Policy     : partition
Hosting Members : ServerOne

Non-Default Attributes Shared By Hosting Members

 Type  |    Name     | Value
------ | ----------- | ---------
Region | size        | 1
       | data-policy | PARTITION
----
====

The PCCDemo app creates fake data on startup, which we can query in Gfsh:

.Query Books
====
[source,txt]
----
gfsh>query --query="SELECT book.isbn, book.title FROM /Books book"
Result : true
Limit  : 100
Rows   : 1

    isbn      | title
------------- | ---------------------
1235432BMF342 | The Torment of Others
----
====

[[cloudfoundry-geode-summary]]
=== Summary

The ability to deploy Spring Boot, {geode-name} `ClientCache` applications to {pcf-name} yet connect your application to
an externally managed, standalone {geode-name} cluster is powerful.

Indeed, this is a useful arrangement and stepping stone for many users as they begin their journey towards Cloud-Native
platforms such as {pcf-name} and using services such as {pcc-name}.

Later, when you need to work with real (rather than sample) applications, you can migrate your Spring Boot applications
to a fully managed and production-grade {pcf-name} environment, and SBDG figures out what to do, leaving you to focus
entirely on your application.
