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 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 Apache/mod_python 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.
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. (Of course, if you are using a trial edition of Cascade, your software installation will automatically stop working after the 90-day trial period has terminated.)
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 info@conifersystems.com 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, /svn or /p4.
Repository URL: The repository you want mapped at this mount point.
For example, svn-http://svn.collab.net/repos/svn.
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.
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 linux, macosx, or
winnt, to select which operating system the worker must be running
in order to run this task.
CPU Architecture: One of x86 or x86_64, to
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
macosx, use 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 arch -x86.)
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.
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
/svn/trunk/foo.txt.
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.
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 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 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.
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.
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. 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., cascade@foobar.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.
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.
Cascade Manager 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.
csc_db_purge takes three command line arguments: the directory
where the Cascade Manager database lives, 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 /var/csc_manager 30 7This purges revisions and tasks older than 30 days and checkpointed changes
older than a week from the Cascade Manager database that lives in the
/var/csc_manager directory.. 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 info@conifersystems.com 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.