LATEST VERSION: 1.9 - CHANGELOG
Push Notification Services v1.8

Installation

This document describes how to install the Pivotal Cloud Foundry (PCF) Push Notification Service.

The PCF Push Notification Service installs as a suite of five CF apps deployed in the system org under the push-notifications space.

  • API
  • Dashboard
  • Service Broker
  • Scheduler
  • Analytics

A default installation deploys 10 Application Instances (AIs), two for each app shown above. For production deployments, Pivotal recommends deploying a minimum of two instances for each push app, 10 AIs total, per PCF environment. Additional API application instances may be required depending on the peak load required, with peak load defined as the maximum number of notifications sent per second.

Dependencies

The Push Notification service depends on MySQL (optionally MySQL for Pivotal CF), RabbitMQ for Pivotal CF, and Redis for Pivotal CF being successfully installed on Pivotal Cloud Foundry.

Download the Product

Download the Push Notification software from Pivotal Network

Adding the Product

To get started with Push, you need to add the product with Pivotal Ops Manager.

Before you can complete the installation you must provide some configuration.

Set Encryption Key

From Ops Manager click on the Pivotal Push Notification Service tile and go to the “Security Settings” section. Generate an encryption key by running the following command in terminal (you should set your own password here):

openssl enc -aes-128-cbc -k samplepassword -P -md sha1

This produces a salt, key, and initialization vector. Copy the key into the “Encryption Key” field on Ops Manager and click “Save”. This key is used for symmetric encryption of push certificates and API keys.

Configure Deployment Settings

From Ops Manager click on the Push Notification Service tile and go to the “Push Deployment Settings” section.

The following deployment options are available:

  • Development: One instance of each service is used by the Push Notification Service tile.
  • Production (default): Two instances of each service are used by the Push Notification Service tile.
  • Custom: Customize how many instances are used for each service. Enter the number of instances, between 1 and 100, for each service.

The following table outlines the resource requirements each service per instance.

Service Memory Usage per instance Disk Usage per instance
Push API 2G 1G
Push Dashboard 512M 1G
Push Broker 512M 1G
Push Analytics 1G 1G
Push Scheduler 512M 1G

Ensure the Diego Cell match the resource requirements for running all instances.

Configure MySQL

From Ops Manager click on the Push Notification Service tile and go to the “MySQL Settings” section. Select MySQL Service to use MySQL for PCF. See the [Installation] section of the MySQL for PCF documentation for more information. When using the MySQL for PCF service for Push Notifications, you must provide a MySQL for PCF service plan name. Pivotal recommends creating a custom MySQL for PCF service plan called “Push”. You can find instructions for creating a custom service plan in the MySQL for PCF Service Plans documentation. After you identify the appropriate service plan, enter its name in the text field, such as “Push”.

To use an external (user provided) MySQL server select “External” and fill in the required fields.

After you have completed this configuration click “Save”.

Configure Redis for Analytics and Logs

From Ops Manager click on the Push Notification Service tile and go to the “Analytics Redis Settings” section. Select the Redis service to use Pivotal Redis service. If you select this option you must install the Pivotal Redis service as well. Select from the drop-down the type of service plan to use. See Pivotal Redis Documentation for more information.

To use an external (user provided) Redis server select “External” and fill in the required fields. - NOTE: This release does not support Redis Cluster if you are using external redis. - If you are using redis behind a tcp proxy, make sure to use Session Persistence.

The same steps apply to set the “Logs Redis Settings” section as above.

After you have completed these configurations click “Save”.

Default Errand Behavior

As of PCF v1.10, Ops Manager skips all unnecessary BOSH errands when performing updates to PCF services. For more information about this behaviour, see the Ops Manager documentation, Managing Errands in Ops Manager.

For PCF Push Notification services, Pivotal strongly recommends that operators set the default Errand execution behaviour to On, through the Errands Form in the Push Notifications tile settings in Ops Manager.

Errands Configuration

Upload Stemcell

Ops Manager versions greater than v1.5 require that you upload the stemcell that the Push Notification Service uses. You can acquire this stemcell from the Bosh Stemcell Directory. After you have the stemcell, upload it to Ops Manager via the “Stemcell” tab in the Push Notification Services configuration page.

Apply Changes

After the security settings and MySQL configuration are complete you can click “Installation Dashboard” to return to the Ops Manager dashboard and then click “Apply Changes” to complete the installation.

Creating a Tenant

Since v1.4, the PCF Push Notification Service supports multiple tenants. Each tenant in the PCF Push Notification Service can have its own set of applications. In order to set up a new tenant, you need to create a new space in your PCF Apps Manager. You can use any org that is appropriate for your needs.

The applications for the Push Notification Service itself are in the “push-notifications” space in the “system” org. Don’t use this space for your own tenant. Create a new space instead.

After you have selected your space you can create your Push service instance by clicking the “Add Service” button. Select the “PCF Push Notification Service” service from the Marketplace. Select the default (free) plan. Give the service a name and add it to your space.

Only create one instance of the Push Notification Service per space.

After the service instance is created you can click the “Manage” link on the service instance to show the Dashboard for the Push Notification Service.

You can control access to the Push Dashboard by using the using Cloud Controller. Any users with access to see the space also have access to use the Push Notification Dashboard. You need to be logged in to the Apps Manager before you can access the Push Dashboard.

Dashboard setup

After the service has been added, verify the successful installation by viewing the dashboard.

Note:

The Push Notification service is a CF Service that is installed in the “System” org and “push-notifications” space. You see it in the Marketplace. Each instance of the Push Notifications Service has its own dashboard URL.

Login as “admin” to the CF console and go to that org and space. To access the Push Dashboard, click on the “Manage” link for the “push-service-instance” service.

Installation Verification

There are two different ways to manually verify the installation was successful.

The first way is to use the CF CLI to view the installed apps and services. Instructions to log in are included on the CF CLI page.

The organization is “System” and the space is “push-notifications”, both are needed to view the apps and services using the CF CLI.

After setting the api and logging in to the CF CLI, type in cf a to see a listing of all the apps currently under the push-notifications space, with a quick overview of their current status.

CLI Apps

The apps that should appear are as follows:

  • Dashboard (push)
  • Backend (push-api)
  • Scheduler (push-scheduler)
  • Analytics (push-analytics)
  • Service Broker (push-service-broker)

And they should all have their own unique urls.

For the services, typing in cf s gives a list of the services plus the apps which they are bound to.

CLI Services

The services that should appear are as follows:

  • MySQL (push-notifications-mysql)
  • RabbitMQ (push-notifications-rabbitmq)
  • Redis for Analytics (push-notifications-analytics-redis)
  • Redis for Logs (push-notifications-logs-redis)
  • Push Notification (push-service-instance)

The second way is to use the developer console. After logging in, select the System organization from the dropdown box. Selecting the organization then shows all of the spaces which are nested within.

Dev Dashboard

Click on the push-notifications space, which then show the apps and services running under that space.

Dev Dashboard Apps

The listing of applications show the status, the name, the url to access the app, how many instances of that app is running, and how much memory that app is using. Verify that each apps status is 100%, which means it is running as expected.

Dev Dashboard Services

The listing of services show the name, the plan, and how many apps are bound to it. Some services have extra options, such as managing the service, or looking up documentation on the service.

Create a pull request or raise an issue on the source for this page in GitHub