# Up and Running with PCF

Examples will use a Spring Boot app

## Prerequisities

- CF CLI installed
- Some instance of PCF running, or access to PWS
- That which is necessary to write/build/run a Spring Boot application
- Understanding of YAML files and what an application manifest is

## First things first

Login:
```
cf login -a <YOUR_PCF_INSTANCE>
```
Will require a username/email and a password on first login.

List commands:
```
cf
```

Get help for a command:
```
cf <COMMAND> --help
```

Target your cf org and space
```
cf target <org> <space>
```

If you need help finding out your org or space, check out
```
cf target --help
```

## CF Push your app
### Build it
From your repository's root, ensure your app's build is up to date with
```
./gradlew clean build
```
assuming your app has the gradle wrapper configured
```
gradle clean build
```
assuming you're relying on a local gradle distribution.

If you're using Maven, do the usual.

### Push it
With your cf cli logged in and your org/space target set, from your repository's root run

```
cf push <DESIRED_APP_NAME_IN_CF> -p <PATH_TO_JAR_OR_WAR> --random-route
```
e.g.
```
cf push cf-demo-app -p build/libs/cf-demo.jar --random-route
```

CF will determine which buildpack to use based on the application type and will then configure and deploy it based on its defaults for that application type. The `--random-route` flag will assign it a random route to prevent collisions with other, already assigned, routes in that CF instance.

The output at the end of the command's run will display its state as 'running', last deployed date/time, cpu usage, memory allocated and in use and most notably the route it has been assigned to/is accessible at.

#### Check it out
With your app successfully pushed, you can now get details on all your deployed apps with
```
cf apps
```

To ge the details of a specific app use
```
cf app <APP_NAME>
```

You can view the configuration the buildpack assigned to the instance with
```
cf env <APP_NAME>
```

### Scale it
If you've decided the buildpack-determined memory, number of instances, etc. is insufficient for your app's needs, you can use
```
cf scale
```
To get the list of options available for your <APP_NAME>.

To apply a change, such as to scale your app from 1 instance to 2, you would use the following:
```
cf scale <APP_NAME> -i 2
```

*Note:* Not only will `cf scale` create more instances of your app, it will retain them under the same route assigned initially and load-balance the requests to this app automatically.

*Note:* Memory/Disk limit changes will require a restart. Setting the available memory to below the minimum threshold for that app type will likely cause it to crash on restart.

### View the logs
To get the most recent logs for your app and the rest of the cloud foundry system relevant to your app, use
```
cf logs <APP_NAME> --recent
```

To tail them in real-time, simply use
```
cf logs <APP_NAME>
```

### View the events
CF outputs a concise audit trail of "events" for the app deployment lifecycle.

To view the events relevant to your app, use
```
cf events <APP_NAME>
```

## Provision & Bind Services
### Find out what's available
While logged into your instance, you can view which services are available for provisioning via the CF Marketplace using
```
cf marketplace
```
or
```
cf m
```
This will show you the services available to you, the plans available for those services and more.

For specific details on a given service, use
```
cf marketplace -s <SERVICE_NAME>
```
e.g.
```
cf marketplace -s p-mysql
```
On my instance would return something similar to
```
cf m -s p-mysql
Getting service plan information for service p-mysql as <your-user>...
OK

service plan   description           free or paid
100mb          Shared MySQL Server   free
1gb            Shared MySQL Server   free
20gb           Shared MySQL Server   free
```

### Mysql DB example
Let's provision a Mysql DB.
To view the options available for the Mysql DB service use
```
cf create-service p-mysql --help
```

For `cf create-service` we must adhere to the following format
```
cf create-service SERVICE PLAN SERVICE_INSTANCE [-c PARAMETERS_AS_JSON] [-t TAGS]
```

For our Mysql DB, we'll then use the following
```
cf create-service p-mysql 100mb demo-db-service
```

On success, the output should read as follows
```
Creating service instance demo-db-service in org your-org / space your-space as your-user...
OK
```

### View your provisioned services
```
cf services
```
will display the services provisioned, the plan it was provisioned on and any apps (by name) bound to that service.

### Bind your service to your app
With the service provisioned, you can now use `cf bind-service` to bind your provisioned service to the app(s) of your choice

e.g.
```
cf bind-service <APP_NAME> demo-db-service
```

With the service bound to your app, you will either have to `cf restage` the app in order to reflect the new environment variables set by the provisioning/binding actions, or `cf restart`.

Restarting the app for environment variable updates is more efficiently than restaging it entirely. On restart, you should be met with output containing the state of your app and its instances.

### View the environment created and bound to your app
To view the details of the Mysql service now bound to your app, you can once again use the command
```
cf env <APP_NAME>
```

Under `VCAP_SERVICES` you will now be able to see the service `p-mysql` along with the details of the provisioned service, including the hostname, jdbcUrl, db name, username/password, port and more.

## Application Manifests
### Create a manifest.yml from a provisioned application

A command exposed by the CF Cli is `cf create-app-manifest <APP_NAME>` which provides a shortcut for creating a CF manifest for the given application.

We can run the command and have the output piped to a file of our choice to create repeatable deployments, distribute via repos and more.

```
cf create-app-manifest <APP_NAME> -p <DESIRED_PATH_TO_OUTPUT_FILE>
```
e.g.
```
cf create-app-manifest demo-app -p ./manifest.yml
```
will produce something similar to
```
applications:
- name: demo-app
  disk_quota: 1G
  instances: 1
  memory: 1G
  routes:
  - route: demo-app-tea-cups.cfapps.io
  services:
  - demo-db-service
  stack: cflinuxfs2
```

The above contains an almost-complete `manifest.yml` for the application we've deployed. We have to add a `path` field with a path to our built file in order for CF to automatically assign a buildpack to our deployment.

```
applications:
- name: demo-app
  path: ./demo-app.jar
  disk_quota: 1G
  instances: 1
  memory: 1G
  routes:
  - route: demo-app-tea-cups.cfapps.io
  services:
  - demo-db-service
  stack: cflinuxfs2
```

The presence of it in our repo root will enable us to `cf push` without `-p <PATH_TO_BUILT_WAR_OR_JAR>`, maintaining the configuration and services bindings every time without having to manually intervene on the commandline or via setting environment variables and `cf restage`-ing or `cf restart`-ing.

We can customize our `manifest.yml` and any changes will be reflected the next time we `cf push` it.