Return to main table of contents
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
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
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.
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.
Administrators have full control over Cascade Manager: they can add or delete users, promote users to administrator status, demote existing administrators to normal user status, change users' passwords, and so on. Make sure you trust anyone you plan to give an administrative account to.
Power users have the ability to edit task configurations, but they do not have any of the other rights associated with administrators. (If you trust anyone to edit task configurations, you could make all non-administrator users power users.)
Normal users cannot edit any Cascade Manager settings, although they still have the ability to browse through all of the non-admin web pages and checkpoint changes.
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.
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 firstname.lastname@example.org with the following information:
...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.
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.)
Mount point: The directory within each Cascade tree where you want
to map this repository. For example,
Repository URL: The repository you want mapped at this mount point.
Username and Password: An account with read access to the repository. This can be left blank if the repository allows anonymous access. This same username and password will be used by Cascade Worker to access the repository when running tasks, so make sure that this account has access to all of the files you will need to access from your builds and tests. Warning: these usernames and passwords are sent to Cascade Worker machines, and any computer with Cascade Worker installed and network access to Cascade Manager can become a worker, so you may not want to put a sensitive username or password here.
Start at Latest Revision: By default, this box is checked. This means that Cascade Manager will enqueue the very latest change made to this repository as the first change it will process. This ensures that Cascade Manager won't spend an extremely long time digging through old changelists; for example, you probably don't want Cascade Manager to enqueue every changelist made to your repository since the beginning. If you clear this checkbox, the "Initial Revision" field becomes available and you can override this behavior.
Initial Revision: If "Start at Latest Revision" is unchecked, you can fill in the first revision you'd like Cascade Manager to process here. For example, "1" means Cascade Manager will look at every revision since your repository was created. This could take a while. You can set this to any value between 1 and the most recent revision number.
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.
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:
Name: Human-readable name that Cascade Manager will use to refer to the task in its web pages. You can set this to anything you want.
Operating System: One of
winnt, to select which operating system the worker must be running
in order to run this task.
CPU Architecture: One of
select what CPU architecture the worker must support in order to run this task.
x86 configurations will still run on 64-bit operating systems that
support 32-bit compatibility mode, while
x86_64 configurations will
only run on 64-bit operating systems. (If you set Operating System to
x86. Macintosh systems use universal
binaries that can run in either 32-bit or 64-bit mode. If you want to force a
binary to run in 32-bit mode on a 64-bit-capable Macintosh system, prefix its
command line with
Current Directory: The current directory under each Cascade tree
where the task should be run from. This path should take the form (for example)
/svn/trunk; that is, it looks like an absolute path, not a relative
path, and its first level is the path of a mount point that you set up earlier
when you added your repositories. Cascade Manager will clean up the path you
give it by converting backslashes to slashes and removing any trailing slash.
Command: The command line of the program you want Cascade Worker to
run. For example,
make to launch GNU make.
Timeout: The number of seconds to wait for the task to complete before giving up, forcibly terminating its process, and declaring that it has failed.
Output Files: The files to gather up and archive as the results of
the task. The format of these paths is the same as for Current Directory, but
you can also specify a relative path here. If you specify a relative path, the
file is located relative to the task's Current Directory. For example, if
Current Directory is
/svn/trunk and you specify an Output File of
foo.txt, this is the same as specifying an output file of
Input Files: If your task depends on another task, you can list the output files of that other task as input files here. A task is not kicked off until all the tasks it depends on have finished. These files will be deposited into your task directory before your task starts. A task is automatically rerun any time any of its input files' contents change.
Environment Variables: The environment variables that should be
set when running this task, beyond the standard default ones. Each entry should
take the form
NAME=value to set the environment variable
to the value
value. On Windows (only), you can reference existing
environment variables with the same
% syntax as in the shell. For
example, to add a directory to
PATH, you might do
Email Recipients: The email addresses that should be notified when the task fails. (These email addresses are ignored unless email support is configured through the admin interface; see Email Settings.)
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
app with the
variable set to
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.
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
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.
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.
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:
Enable Email: Check this box to enable sending of email.
SMTP Hostname: The hostname of the computer running the SMTP server that you want Cascade Manager to connect to.
SMTP Username and SMTP Password: To prevent spam, many SMTP servers require you to authenticate with a valid username and password before you can send email. You can fill in the username and password here. If you leave the username blank, the password will be ignored and Cascade Manager will send the email without attempting to authenticate with your SMTP server. Warning: any password you type here can be extracted out by anyone with administrative access to Cascade Manager or direct access to the Cascade Manager database on the computer hosting Cascade Manager, so you may not want to put a sensitive username or password here.
From Address: The email address that the email should appear
to be sent from, e.g.,
email@example.com. Some SMTP servers may
allow you to provide any email address of your choice here, while others may
reject "from" addresses that do not match the server's domain name or your SMTP
username. You may want this to point to a valid email address in order to
receive bounce messages when an email is undeliverable.
Cascade Manager URL: In order to put correct URLs in the emails it
sends, Cascade Manager needs to know its own URL. This takes the same format as
in other places in Cascade, e.g.,
http://hostname/cascade. It is
recommended that you not use
localhost as the hostname here, since
localhost has a different meaning depending on which computer the
user reads their email from.
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.
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
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.
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
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 firstname.lastname@example.org 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.