Pivotal Tracker

Product Snapshot

Current Pivotal Tracker Details
Version: 1.3.1.7
Release Date: 7 June 2016
Compatible Ops Manager Version(s): 1.7.x, 1.6.x, 1.5.x
Compatible Elastic Runtime Version(s): 1.7.x, 1.6.x, 1.5.x
vSphere support? Yes
AWS support? Yes
OpenStack support? No

Note: Pivotal Tracker for PCF (Pivotal Cloud Foundry) is deprecated and availability is restricted to existing customers. Contact Support for more information.

Upgrading to the Latest Version

Consider the following compatibility information before upgrading Pivotal Tracker.

Ops Manager Version Supported Upgrades
1.3.x None. 1.1.1.0 is the only release available for Ops Manager 1.3.x.
1.4.x
  • From 1.2.1.5 to 1.2.1.9, 1.2.1.10
  • From 1.2.1.9 to 1.2.1.10
  • From 1.2.1.10 to 1.2.1.14
  • From 1.2.1.14 to 1.2.1.15
1.5.x
  • From 1.2.1.9 to 1.2.1.10
  • From 1.2.1.10 to 1.2.1.14
  • From 1.2.1.14 to 1.2.1.15
  • From 1.2.1.15 to 1.3.1.2
  • From 1.2.1.15 to 1.3.1.4
  • From 1.2.1.15 to 1.3.1.5
  • From 1.2.1.15 to 1.3.1.7
  • From 1.3.1.2 to 1.3.1.4
  • From 1.3.1.2 to 1.3.1.7
  • From 1.3.1.4 to 1.3.1.7
  • From 1.3.1.5 to 1.3.1.7
1.6.x
  • From 1.3.1.1 to 1.3.1.2
  • From 1.3.1.2 to 1.3.1.4
  • From 1.3.1.2 to 1.3.1.7
  • From 1.3.1.4 to 1.3.1.7
  • From 1.3.1.5 to 1.3.1.7
1.7.x
  • From 1.3.1.1 to 1.3.1.7
  • From 1.3.1.2 to 1.3.1.7
  • From 1.3.1.2 to 1.3.1.7
  • From 1.3.1.4 to 1.3.1.7
  • From 1.3.1.5 to 1.3.1.7

Software Requirements

  • Ops Manager 1.5 or later
  • Elastic Runtime 1.5 or later, with SMTP configured
  • Ruby Buildpack 1.6.8 installed as ‘p-tracker_buildpack’
  • MySQL 5.5 or later database (optionally MySQL for PCF)

Infrastructure Requirements

  • Two Persistent VMs
    • Memcached: 512MB RAM, 1GB ephemeral disk
    • Solr: 2GB RAM, 1.5GB ephemeral disk, 3GB persistent disk
  • Two Ephemeral VMs
    • Push/Delete Errands: 512MB RAM, 2GB ephemeral disk
    • Compilation: 1GB RAM, 2GB ephemeral disk
  • Two Elastic Runtime Apps
    • tracker-app: 1.5GB RAM, 1GB ephemeral disk
    • tracker-workers: 1GB RAM, 1GB ephemeral disk

Minimal Pivotal Tracker installation: 4GB RAM, 4.5GB ephemeral disk, 3GB persistent disk. Additional tracker-app instances: 1.5GB RAM, 1GB ephemeral disk.

Important Notes

Data Backups

Pivotal Tracker does not yet back up any data it stores in the MySQL or blobstore services. Please work with your Pivotal Representative to ensure that proper backup and recovery policies are in place.

Database and Blobstore Sizing

On average, an active user consumes ~23KB of DB storage and ~100KB of blobstore storage per day. An “active” user is defined as one that makes changes in Pivotal Tracker on a daily basis.

Migrating from MySQL for PCF to External Database

Given the following scenario: Pivotal Tracker was configured to use MySQL for PCF, and end-users have data stored in Pivotal Tracker (projects, stories, etc.). If Pivotal Tracker is subsequently reconfigured to use an external database in Ops Manager, the MySQL data will be automatically deleted upon the next installation in Ops Manager. Be sure to migrate the existing database to the new, external database prior to doing this. Please work with your Pivotal Representative for more details.

Migrating from Riak CS for PCF to External Blobstore

Given the following scenario: Pivotal Tracker was configured to use Riak CS for PCF, and end-users have data stored in Pivotal Tracker (specifically, attachment uploads are stored in the blobstore). If Pivotal Tracker is subsequently reconfigured to use an external blobstore in Ops Manager, the Riak CS data will be automatically deleted upon the next installation in Ops Manager. Be sure to migrate any blobstore objects that you want to preserve to the new blobstore prior to doing this. Please work with your Pivotal Representative for more details.

Installation Prerequisites

Pivotal Tracker Buildpack

To ensure the required version of Ruby is available for Pivotal Tracker, the Ruby Buildpack 1.6.8 must be uploaded to Elastic Runtime as “p-tracker_buildpack”. After downloading the buildpack from Pivotal Network, upload it as an administrator to Elastic Runtime with the “cf” CLI:

cf create-buildpack p-tracker_buildpack ruby_buildpack-cached-v1.6.8+1446579066.zip 99 --enable

Refer to the Adding Buildpacks to Cloud Foundry documentation for more information.

Pivotal Tracker Admin User

As part of the Pivotal Tracker configuration in Ops Manager (see Pivotal Tracker Admin Email below), an Elastic Runtime user must be specified to function as the Pivotal Tracker Administrator. This user does not need administrative privileges for Elastic Runtime though.

The Pivotal Tracker Admin User must already exist in the Elastic Runtime User Database (“UAA”). The user will not be automatically created upon installation of the Pivotal Tracker product.

NOTE: This user does not require any org or space permissions, since the account is not used for Elastic Runtime PaaS functions. This user will be granted administrative privileges only within the Pivotal Tracker application; installation of Pivotal Tracker does not modify the UAA Administrator permissions.

Pivotal Tracker Internal Support Email

As part of the Pivotal Tracker configuration in Ops Manager, an email must be specified that will serve as first-tier support for users of Pivotal Tracker. For more details see Pivotal Tracker Internal Support Email below.

Install via Ops Manager

To install Pivotal Tracker, follow the procedure for installing Ops Manager products:

  1. Download the product file from Pivotal Network.
  2. Upload the product file to your Ops Manager installation.
  3. Click Add next to the uploaded product description in the Available Products view to add this product to your staging area.
  4. Click the newly added tile to review any configurable options.
  5. Click Apply Changes to install the product.

Product Configuration

Assign Networks

Assign the Network which should be used by Pivotal Tracker. See the Ops Manager Director tile configuration and documentation for more information.

Assign Availability Zones

Assign the Availability Zones which should be used by Pivotal Tracker. See the Ops Manager Director tile configuration and documentation for more information.

Pivotal Tracker Config

Subdomain of Pivotal Tracker app

Enter the subdomain which should be used by Pivotal Tracker. This will be prepended to the System Domain configured in the Cloud Controller tab of Pivotal Elastic Runtime. For example, if the System Domain is system.cf.biz and the subdomain is tracker, Pivotal Tracker will be available to users at tracker.system.cf.biz.

App Salt

Enter a random string. This string is used as a salt when encrypting Pivotal Tracker user passwords. This must remain the same when re-installing Pivotal Tracker and using an existing database, otherwise pre-existing user passwords will not work after re-installation.

Pivotal Tracker Admin Email

Enter the email of the Elastic Runtime user who will serve as the Pivotal Tracker Administrator.

Pivotal Tracker Internal Support Email

Enter the email address where support requests from Pivotal Tracker users will be sent. For example, this might be the email for your internal helpdesk queue. This email is displayed on the Pivotal Tracker Help page, FAQ page, and error page (when the server returns HTTP status code 500).

Number of App Instances

This specifies the number of Elastic Runtime application instances to use for Pivotal Tracker web application. Increase for more redundancy and/or scalability. E.g., if you want the Pivotal Tracker web app to remain available even if one of the web app instances is restarted, set this to 2.

Blobstore Config

Riak CS Service

By default, Pivotal Tracker uses a Riak CS for PCF service instance to store file uploads attached to Pivotal Tracker Stories. Specify the Riak CS service plan to use when provisioning the Pivotal Tracker blobstore.

External Blobstore

If you prefer to use an external S3-compatible blobstore, enter the necessary configuration details.

WARNING: Reconfiguring Pivotal Tracker to use an external blobstore will delete any existing Pivotal Tracker Riak CS for PCF service and its associated data.

Database Config

MySQL Service

By default, Pivotal Tracker uses a MySQL for PCF service instance to store data. Specify the MySQL service plan to use when provisioning the Pivotal Tracker database. Refer to the MySQL Service Plan documentation for more information.

External Database

If you prefer to use an external MySQL-compatible database, enter the necessary configuration details.

WARNING: Reconfiguring Pivotal Tracker to use an external database will delete any existing Pivotal Tracker MySQL for PCF service and its associated data.

Errands

The Push Pivotal Tracker errand should always be enabled when installing, upgrading, or changing configuration of the Pivotal Tracker product.

Elastic Runtime Details

The Push Pivotal Tracker errand deploys and configures Pivotal Tracker apps in the Elastic Runtime PaaS.

It uses the system_services Elastic Runtime user to:

  1. Create a pivotal-tracker Space under the system Org
  2. Provision MySQL and Blobstore service instances
  3. Push the Pivotal Tracker Web and Worker apps to Elastic Runtime

Resource Config

You may change the resource configuration, but the defaults should be sufficient for most Pivotal Tracker installations.

Architecture Overview

Architecture overview

Usage

Logging

Pivotal Tracker Web and Worker apps log via Elastic Runtime Loggregator.

Logs for Pivotal Tracker Memcached and Solr jobs are available from the Logs section in Ops Manager.

App Status

Pivotal Tracker has some pages which expose information about the status and health of the app:

Env Info

  • URI: https://<yourdomain>/env_info
  • Access: Anyone with access to the domain can see this information, without being logged in to Elastic Runtime.
  • Description: Provides status on the various components and services which are part of or support Pivotal Tracker. If problems with any of these are detected, they will be reported on this page. The 'index’ page is a summary of all components except 'attachments’, with links to pages for individual components

Env Info Attachments

  • URI: https://<yourdomain>/env_info/attachments
  • Access: Anyone with access to the domain can see this information, without being logged in to Elastic Runtime.
  • Description: Provides status on the blobstore, for either the default Riak CS blobstore or an external blobstore. This information is not available on the the env_info “index” page.

Private Install Info

  • URI: https://<yourdomain>/private_install_info
  • Access: Only an authenticated Pivotal Tracker Admin user can view this page.
  • Description: Provides detailed information on all Environment Variables which are present in the running Pivotal Tracker environment. It also provides information on the license and users, but there are currently no license limits enforced in the Pivotal Tracker Cloud Foundry product.

Pivotal Tracker Administration

The Pivotal Tracker Admin can access various pages to control the appearance and behavior of the application. These are only accessible to an authenticated Pivotal Tracker Admin user, and can be reached via the “admin” link in the header.

Admin FAQ

  • URI: https://<yourdomain>/admin/single_account_mode_admin_faq
  • Description: Answers frequently asked questions for the Pivotal Tracker Admin user.

Projects

  • URI: https://<yourdomain>/admin/find_projects
  • Description: Allows the Admin to search, create, view, update, or delete projects.

People

  • URI: https://<yourdomain>/admin/people
  • Description: Allows the Admin to search, create, view, update, or delete people. See User Administration for more information on adding and removing members.

API Tokens

  • URI: https://<yourdomain>/admin/tokens
  • Description: Allows the admin to search and view Pivotal Tracker API Tokens.

Maintenance

  • URI: https://<yourdomain>/admin/maintenance_periods
  • Description: Allows the Admin to search, create, view, or delete maintenance periods. This will cause periodic “countdown” alerts to be shown to users.

User Administration

Account Email Validation

Note that Pivotal Tracker has stricter validation rules for a “valid” email address when compared to the Elastic Runtime UAA. It’s possible an Elastic Runtime user was provisioned with an email such as user@hostname, which will fail validation when attempting to log in to Pivotal Tracker. We plan to address this limitation in a future release of Pivotal Tracker; in the meantime, the email will need to be changed by an Elastic Runtime administrator to an acceptable address such as user@hostname.com.

Inviting Users to a Pivotal Tracker Project

New Pivotal Tracker users can be invited via the Project “Add/Remove Members” page. Users can be added to multiple projects.

  1. Type in a valid email address of an Elastic Runtime user in the “Add a project member” field, assign the desired role, and click “ADD”.
  2. The user will receive an email with a link which will allow them to finish the invitation process.
  3. The invited person does not need to be an existing Elastic Runtime user at the time of invitation. If the invitee is a new user, they must complete the Elastic Runtime signup process before they can accept the Pivotal Tracker project invitation.

Self-service Signup of New Users

Because Pivotal Tracker uses the Elastic Runtime for user authentication, the ability for end-users to self-provision their own Pivotal Tracker accounts depends on the configuration of Elastic Runtime. Specifically, refer to the Apps Manager documentation pertaining to the ENABLE_NON_ADMIN_USER_MANAGEMENT configuration option.

Suspended Users

If a Pivotal Tracker user account is suspended by the Pivotal Tracker Administrator, the affected user will get an HTTP 500 response when trying to authenticate to Pivotal Tracker.

Password Reset

Pivotal Tracker users do not have the ability to reset their password. If a password is forgotten and needs to be reset, they will need to contact an Elastic Runtime administrator.

Support

Email tracker-pcf@pivotal.io with questions or problems.

Reporting Problems

When reporting problems, please provide as much of the following information as possible or appropriate:

  • Steps to reproduce the problem including expected behavior and actual behavior
  • The URL of the page(s) involved
  • Any error messages shown
  • A screenshot/screencast showing the problem
  • Any relevant logs (see the “Logging” section above for details)
  • A screenshot or PDF of the /env_info and /env_info/attachments pages

Migrating Data to an External Database

Outlined below are the steps to migrate Pivotal Tracker data stored in a MySQL for PCF service instance to an external MySQL database. If any of the steps below aren’t clear, please contact us for support.

Gather Prerequisite Information

MySQL for PCF Service Instance Credentials

Log in to Pivotal Tracker with the admin account and navigate to https://<yourdomain>/private_install_info. Find the DATABASE_URL entry, which will be in the following format: mysql2://TRACKER_DB_USER:TRACKER_DB_PASSWORD@TRACKER_DB_HOST:3306/TRACKER_DB_NAME?reconnect=true. Record the database user, password, and name. For example:

Credential Name Example Value
TRACKER_DB_USER zmiXBCnJUXdWOlk4
TRACKER_DB_PASSWORD 96hsLUvnP9l4GYqP
TRACKER_DB_NAME cf_aca7137f_49b7_4926_a96b_b053659c5bd4

From Ops Manager, click on the MySQL for PCF tile. Go to the 'Credentials’ tab and record the VM Credentials for the MySQL Server job. Go to the 'Status’ tab and record one of the IPs listed under the MySQL Server job. For example:

Credential Name Example Value
MYSQL_VM_USER vcap
MYSQL_VM_PASSWORD 4cde067ab5f331fa
MYSQL_VM_IP 10.85.58.147

External MySQL Database Credentials

For the external database, record the hostname, port, user, password, and database name. For example:

Credential Name Example Value
EXTERNAL_DB_HOSTNAME db-host01.my-corp.com
EXTERNAL_DB_PORT 3306
EXTERNAL_DB_USER mysql-tracker-user
EXTERNAL_DB_PASSWORD 0xCOFFEE
EXTERNAL_DB_NAME ext_tracker_db

Unmap Pivotal Tracker Route

To prevent Pivotal Tracker users from adding new data while the migration takes place, map the application route to a new URL that is unknown to users. For example: map tracker.system.cf.biz to tracker-maintenance.system.cf.biz. For instructions on modifying routes, refer to the Assign or Change a Route documentation.

Export Data to Backup File

Run the following command to export Pivotal Tracker data to the local file /tmp/tracker_db_backup.sql:

ssh MYSQL_VM_USER@MYSQL_VM_IP /var/vcap/packages/mariadb/bin/mysqldump \
 -u TRACKER_DB_USER -p TRACKER_DB_NAME > /tmp/tracker_db_backup.sql

You will be prompted for the credential MYSQL_VM_PASSWORD, followed by TRACKER_DB_PASSWORD. For example:

$ ssh vcap@10.85.58.147 /var/vcap/packages/mariadb/bin/mysqldump \
 -u zmiXBCnJUXdWOlk4 -p cf_aca7137f_49b7_4926_a96b_b053659c5bd4 > /tmp/tracker_db_backup.sql
Ubuntu 14.04.3 LTS \n \l

vcap@10.85.58.147's password:
< enter 4cde067ab5f331fa >
Enter password:
< enter 96hsLUvnP9l4GYqP >

Verify the data was exported by checking the contents of /tmp/tracker_db_backup.sql.

Import Data to External Database

Run the following command to import the Pivotal Tracker data into the external database:

mysql -h EXTERNAL_DB_HOSTNAME -P EXTERNAL_DB_PORT -u EXTERNAL_DB_USER -pEXTERNAL_DB_PASSWORD EXTERNAL_DB_NAME \
 < /tmp/tracker_db_backup.sql

Note: There is no space between -p and EXTERNAL_DB_PASSWORD. For example:

$ mysql -h db-host01.my-corp.com -P 3306 -u mysql-tracker-user -p0xCOFFEE ext_tracker_db \
 < /tmp/tracker_db_backup.sql

When the import is complete, log in to the external database and verify the data is populated. For example:

mysql> SELECT * FROM person LIMIT 5 \G
...
mysql> SELECT * FROM story LIMIT 5 \G

Configure Pivotal Tracker to Use External Database

From Ops Manager, click on the Pivotal Tracker tile and choose the Database Config section. Select the option to use an External Database and fill in the required information. Save the changes.

Ensure that the Push Pivotal Tracker errand is enabled in the Errands section.

Return to the Ops Manager Installation Dashboard and click the Apply Changes button. Note: After applying changes, the existing Pivotal Tracker database in MySQL for PCF will be destroyed.

Post-Installation Steps

Log in to Pivotal Tracker and verify the data was migrated (users, projects, stories).

Delete the un-needed maintenance route; the original route (e.g. tracker.system.cf.biz) was re-mapped as part of the Push Pivotal Tracker errand.

Was this helpful?
What can we do to improve?
View the source for this page in GitHub