Cascade Manual: Cascade Manager

Return to main table of contents

Table of Contents:

  1. Accessing Cascade Manager
  2. Creating and Managing Users
  3. License Management
  4. Adding Repositories
  5. Task Configurations
  6. Starting/Stopping Cascade Manager
  7. Revisions and Tasks
  8. Email Settings
  9. Purging Logs, Old Checkpointed Changesets, and Task Results

Accessing Cascade Manager

Most user interaction with Cascade Manager takes place through a web browser. After installing Cascade Manager, bring up your web browser and point it to the Cascade Manager URL. This is typically http://hostname/cascade, https://hostname/cascade, or http://hostname:8080, where hostname is the hostname of the computer running Cascade Manager. (The former two are used for WSGI installations of Cascade Manager, while the latter is used by the default Windows "standalone" installation of Cascade Manager.) If you are running Cascade Manager off your own local desktop, hostname is simply your own computer's hostname.

When you access Cascade Manager, your web browser may prompt you to log in. When prompted, you will need to provide a valid Cascade Manager username and password.

At the top of each Cascade Manager web page is a navigation bar. This provides quick access to most of the important Cascade Manager web pages.

Creating and Managing Users

When you first access Cascade Manager after installing it, you will see a warning in bold text informing you that you are logged in anonymously and that, until you set up at least one user, anyone has administrative access to the system. Click on the provided "user management" link (also available through the navigation bar at "Admin", "User Management") to create your first user, who will also be a Cascade Manager administrator.

Cascade Manager users can be normal users, power users, or administrators.

To add a user, simply provide a username and password, select which type of user this is, provide the person's real name and email address, and click "Add". After creating your first user, you will be prompted to log in; simply provide the same username and password you just added earlier.

The User Management page also provides a table of all existing users, with administrators highlighted in green and power users highlighted in blue. You can edit a user's information (including changing their password) or delete a user here.

License Management

You do not need to enter a license key to install the Cascade software. Instead, license management of Cascade is performed through Cascade Manager. Cascade Manager automatically allows you to run with a single user without needing to enter a license key. This allows you to create your first administrative account, as described above, or to use Cascade in a single-user environment. However, if more than one person will use Cascade, you will need to obtain a license key for each user (including the first user—that is, you need 3 licenses, not 2, for 3 users).

To obtain a set of trial license keys, which will expire 90 days after issuance, please email with the following information:

  1. Number of users (we will issue you a separate trial license key for each user)
  2. Your name and your organization's name
  3. The email address we should use for Cascade-related communications

...and we will email you back your trial license keys. Please ask for enough keys that you won't run out. If you need additional trial license keys, though, please feel free to contact us again.

You can enter these license keys into the License Management page ("Admin", "License Management" on the navigation bar), and it will allow you to create one user per license key. The web page will show the current status of your license keys, including how many users are currently licensed and how long before those licenses expire.

As a paying customer, we will issue you license keys that last for a full year. Please email us for more information on buying licenses.

Adding Repositories

The next step in setting up Cascade Manager is to tell it about one or more repositories for it to monitor. Cascade Manager will keep track of the changes committed to these repositories.

To add a repository, click "Admin", "Add Repository" on the navigation bar, fill in the form, and click the "Add" button. (Only administrators can add repositories.)

If you make a typo or other mistake in setting up a repository, you can delete it from the Repositories page by clicking the "delete" link. Make sure the repositories information is all correct before starting Cascade Manager, because once Cascade Manager has been started and workers have started running tasks, changing the repositories information requires that you delete your Cascade Manager database and restart from scratch.

Task Configurations

Setting up tasks is (strictly speaking) optional, but we recommend that you set up at least one task, even if it's a very simple one, to start taking advantage of Cascade's "clone last known good" functionality. For example, you might want to set up a build of at least one component or build configuration. This way, when someone clones last known good, they will get a tree where this component is known to build successfully. You can always reconfigure your tasks later.

Power users and administrators can add, edit, or delete task configurations, while normal users cannot. This privilege is not restricted to administrators because that would likely make your administrators a bottleneck in keeping the task configurations up to date.

To set up configurations, click "Configs" on the navigation bar. This page shows a table of your existing configurations with "edit" and "delete" links, plus a form for adding new configurations.

It's important to understand that configurations are versioned. While we use the familiar terminology of "edit" and "delete", it's not strictly possible to "edit" or "delete" most properties of an existing configuration. To be more precise, "delete" simply deactivates the configuration, so that when future changes are committed to the repository, the task in question will not be kicked off. Existing tasks at previous revisions will continue to run. Similarly, "edit" does not affect existing queued-up or running tasks; an "edit" is really an atomic "delete"/"add" pair, unless you are editing only a configuration's name or its list of email addresses (all other properties of a configuration are immutable).

Each configuration has the following properties:

A task is deemed to have "succeeded" if it returns an exit code of zero, while it is deemed to have "failed" if it returns a nonzero exit code. Output files don't enter into whether a task "succeeds" or "fails"; it's possible for a failing task to generate output files, or for a passing task to not generate any output file. If you want to check for the existence of a file and have your task fail if the file does not exist, we recommend that you write a wrapper script around your program to check for this.

On Windows, tasks inherit their default environment variables from their parent Cascade Worker process. Cascade Worker runs as a service, however, so it will not pick up any "per-user" environment variables that have been set, only system-wide environment variables.

On Linux and Mac OS X, tasks start with a clean default environment containing just one environment variable: PATH=/usr/local/bin:/usr/bin:/bin. This allows you to run most normal Unix applications. If your task needs more environment variables set, you can specify them at the start of the command line just like in the Unix shell. For instance, LD_LIBRARY_PATH=/x/y/z app will run the program app with the LD_LIBRARY_PATH environment variable set to /x/y/z.

Once you've kicked off Cascade Manager and its workers, any time you add or edit a task, this will immediately kick off the task and any other tasks that depend on it. There's no need to commit a dummy "force the task to be rerun" change to your repository.

Starting/Stopping Cascade Manager

Once you have set up your repositories and initial tasks, click on "Admin" on the navigation bar. This page has a button labeled either "Start" or "Stop". This setting controls Cascade Worker clients. When Cascade Manager is stopped, Cascade Worker will not start executing any new tasks, nor will Cascade Manager look for any new committed changes in your repositories. To kick off your workers, click "Start".

If you want to stop the workers from launching new tasks again, click "Stop". You would typically do this if you want to shut down Cascade entirely, say, for an OS upgrade requiring a reboot on the server running Cascade Manager. Clicking "Stop" does not immediately terminate tasks that are already running, so after clicking "Stop", you would wait for the existing tasks to finish before rebooting the server. Once the server is back up, you can click "Start" again.

Note this is entirely distinct from the Windows concept of an NT service being "started" or "stopped", or the equivalent Unix concept of starting or stopping a daemon. On a Windows system, clicking "Stop" on the Admin page does not shut down the Cascade Manager web server entirely; it only prevents new tasks from being launched. On the other hand, typing net stop csc_manager at a command prompt will completely shut down Cascade Manager. Cascade Worker clients will not be able to report the completion of the tasks they are currently working on, nor will you be able to access any of the Cascade Manager web pages. To shut down Cascade Manager in an orderly fashion, it is recommended that you click "Stop" in the web interface first and wait for existing tasks to complete.

Revisions and Tasks

These pages show you the overall status of the system. The Revisions page gives you a higher-level view of what's going on (one table row per committed or checkpointed change), while the Tasks page gives a lot more detail (one table row per task; a single change can kick off many tasks).

Rows in these tables are color-coded. Blue rows represent tasks that have not started running yet. These tasks are in the "ready" state (ready to run as soon as a worker finishes running another task and becomes available) or the "waiting" state (still waiting for a previous task to complete). Green rows represent tasks that are running right now. Red rows represent tasks that have completed and failed. White rows represent tasks that have completed and passed.

Revisions with a dot (e.g. "5.2") represent checkpointed changes. For example, revision 5.2 would be the second checkpointed change created so far relative to revision 5. (Note that "5.1" and "5.10" are not the same thing.)

Clicking on a revision will show you more information about that particular revision: who committed it, when, its description, what files it modified, and so on. It will also show you a smaller table, similar to the one on the Tasks page, with the status of the tasks run at that specific revision.

Clicking on a task will also show you a bit more information about it. Often you will just want to see the log, so a shortcut link is provided directly to the log.

Email Settings

Cascade Manager can optionally send emails informing users about the results of tasks. To set up email support, click "Admin", "Email Settings" on the navigation bar. (If you do not configure email support, Cascade Manager will not send any emails.)

Cascade Manager sends email by connecting to an SMTP server. This server need not be running on the same computer as Cascade Manager. Currently, Cascade Manager only supports the non-encrypted variant of SMTP that runs on port 25. The encrypted versions of SMTP that run on ports 465 and 587 are not supported.

This page has the following fields:

Once you have configured the email settings and enabled email, you should send a test email to make sure that email is working. To do this, enter a destination email address and click the "Send Test Email" button. If all is working well, you should receive an email at that address. If there is a problem, e.g., Cascade Manager is unable to connect to your SMTP server, you should see an error here. If you do not see an error message but are still not receiving test emails, check with the system administrator who runs your email system to make sure the email is not being blocked, e.g., by a spam filter. You may also want to check the email box of the "From Address" to see whether your email has been bounced.

When a task fails, Cascade Manager will email the user who checkpointed or committed the change. Cascade Manager uses the usernames and email addresses in its own user database to identify this user's email addresses, so make sure to use the same usernames in Cascade Manager as in Perforce or Subversion for the email feature to work most effectively.

In addition, on a commit, Cascade Manager will also email the email addresses listed in the task's configuration. These email addresses will not be emailed on a failed task from a checkpoint, only a commit.

Purging Logs, Old Checkpointed Changesets, and Task Results

Cascade Manager writes a log of database transactions to a file named log in its database directory. This file's size will grow without bound over time unless you delete it. You can delete this file with no ill effects at any time.

Cascade Manager also includes a program named csc_db_purge. To purge old, unneeded data from your database to free up disk space, you can run this program from a command prompt on the server where Cascade Manager is hosted.

Warning: csc_db_purge irreversibly destroys data. We recommend that you back up your database before running it.

csc_db_purge takes two command line arguments: the number of days back to keep old task results and the number of days back to keep old checkpointed changes. Here is an example of its usage:

csc_db_purge 30 7

This purges revisions and tasks older than 30 days and checkpointed changes older than a week from the Cascade Manager database. Note that some task results older than 30 days may not be purged if the task has not run at least once within the last 30 days. This is expected behavior; Cascade Manager always needs to preserve the most recent run of any task.

You might want to set up csc_db_purge as a cron job to run automatically every so often, e.g., once a week during the weekend. It's probably best if you don't run csc_db_purge during normal work hours—it can take a while to run, and it will lock other users out of the database during this time.

Comments or questions about the manual? Please email with your feedback.

Copyright © 2008 Conifer Systems LLC. All rights reserved.

Cascade contains valuable trade secrets and other confidential information belonging to Conifer Systems LLC. This software and its associated documentation may not be copied, duplicated or disclosed to third parties without the express written permission of Conifer Systems LLC.