Cascade 1.2.0.1069 Manual: Installation

Return to main table of contents

Table of Contents:

  1. Cascade System Requirements
  2. Which Components to Install?
  3. Windows Installation Instructions
    1. Windows Shell Extension Icon Overlays and TortoiseOverlays
  4. Linux Installation Instructions
    1. Check prerequisites
    2. Upgrade pysqlite
    3. Make sure /usr/local/lib is listed in /etc/ld.so.conf
    4. Configure FUSE
    5. Run the installer
    6. Set up Cascade Manager as a WSGI application
    7. Run Cascade Worker service
  5. Macintosh Installation Instructions
    1. Check prerequisites
    2. Set up user for Cascade Worker
    3. Upgrade pysqlite
    4. Run the installer
    5. Set up Cascade Manager as a WSGI application
    6. Run Cascade Worker service
  6. Firewalls
  7. Windows WSGI Instructions
    1. Install Cascade
    2. Install Apache
    3. Install Python
    4. Upgrade pysqlite
    5. Install mod_wsgi
    6. Add Cascade Manager entry to Apache conf file
    7. Disable the standalone Cascade Manager web server
  8. Storage Size
  9. Upgrading an Existing Cascade Installation
    1. Network Protocol Compatibility
    2. Cascade Cache File Format Compatibility
    3. Cascade Manager Database File Format Compatibility

Cascade System Requirements

Windows:

Linux:

Macintosh:

Which Components to Install?

Each end user should install the Cascade client software—Cascade File System, the command line client, and (for Windows users) the shell extension—on each computer where they intend to use Cascade.

End users may also wish to install Cascade Worker, if you intend to run tasks off individual users' PCs in addition to or instead of on a dedicated cluster. Each installation of Cascade Manager must have at least one Cascade Worker client.

End users generally do not need to install Cascade Manager on their own PCs. Cascade Manager should only be installed on one PC shared across the entire team using Cascade. Or, if you are the only person on your team using Cascade, you can simply install Cascade Manager on your own local PC. Cascade Manager doesn't need to run off its own a dedicated server, but it's strongly recommended that whatever computer you choose be "always on".

Using Cascade Proxy is completely optional; all Cascade functionality works without Cascade Proxy, though with reduced performance. If more than one person is planning on using Cascade, however, we recommend that you set up at least one proxy on a shared, "always-on" PC to increase performance—this will ensure that redundant queries are not made to your repository server. Using a proxy may even be beneficial in a single-user setup if you use Cascade from multiple PCs.

You don't need to explicitly install Cascade Proxy. The Cascade Proxy server is built into the Cascade File System service.

Additional proxies can be added to increase performance. At minimum, we recommend that you set up another proxy at each remote office or site using Cascade, and chain each of these proxies to your main proxy—this way, when the proxy has a cache miss, it will send the request first to your main proxy rather than sending the request straight to your repository server.

Windows Installation Instructions

To install Cascade under Windows, run the .msi file by double-clicking on it and follow the instructions.

If you are running an "x64" (64-bit) version of Windows, you should run the x86_64 .msi file, not the x86 .msi file. 64-bit users may also want to install the 32-bit shell extension so that 32-bit apps can also access the shell extension, but this is optional. (When you run the 32-bit .msi under 64-bit Windows, all other Cascade features, such as Cascade File System, will automatically be hidden in the installer—you'll only be given the option to install the shell extension, and nothing else.)

When you reach the "Cascade Configuration" page of the installer:

If you have installed a Microsoft Loopback Adapter as required by previous versions of Cascade, you can uninstall it now. Cascade no longer requires the Microsoft Loopback Adapter to be installed.

Windows Shell Extension Icon Overlays and TortoiseOverlays

The Cascade Windows shell extension uses icon overlays to show the state of files: unmodified, edited, added, or merge needed. The Windows shell does not allow more than 15 types of icon overlays system-wide, so if other programs are using too many icon overlays already, some or all of the Cascade icon overlays will not show up. Alternatively, Cascade may prevent other programs' icon overlays from showing up.

There is no additional harm to exceeding the limit of 15 icon overlays—the only problem is that some of the icon overlays will not show up.

Icon overlays are used by the "Tortoise" shell extensions for revision control systems—TortoiseCVS, TortoiseSVN, etc. Historically, this problem has also afflicted users of the Tortoise programs, since installing just two of them on your computer would already push you over this Windows limit.

The TortoiseSVN project recently shipped a shared component called TortoiseOverlays that solves the problem by allowing any number of shell extensions to share the same set of icon overlays. Cascade also makes use of TortoiseOverlays—when you install Cascade, TortoiseOverlays will also be installed on your computer automatically. Unfortunately, not all of the Tortoise programs have added TortoiseOverlays support yet.

TortoiseSVN 1.5.x is the first release of TortoiseSVN to incorporate TortoiseOverlays. If you have TortoiseSVN installed, we recommend that you upgrade to 1.5.x.

TortoiseCVS has not yet shipped a TortoiseOverlays-based release, but the changes to support TortoiseOverlays are in their CVS repository, so their next release will likely add this feature.

Linux Installation Instructions

Check prerequisites

Upgrade pysqlite

Python 2.5.2 is bundled with pysqlite 2.3.2. If you are planning to host Cascade Manager off this machine, you should install pysqlite 2.5.0 or newer to pick up several important bug fixes. You can download the source distribution and find installation instructions at the pysqlite web site. If you don't upgrade pysqlite, you may encounter occasional hangs when multiple clients attempt to access the database concurrently.

If you are not hosting Cascade Manager off this computer, you can skip this step.

Make sure /usr/local/lib is listed in /etc/ld.so.conf

Some Linux distributions automatically include /usr/local/lib in /etc/ld.so.conf, the list of paths where programs will automatically search for .so files. Others, e.g., many Red Hat distributions, do not. Cascade installs several .so files into /usr/local/lib, so you will need to make sure that these can be found.

To add this path, bring up /etc/ld.so.conf in your text editor and, if it isn't already present in the file or in one of the other conf files included by the top-level ld.so.conf, add a new line /usr/local/lib.

Configure FUSE

Run the installer

From whatever directory you like, type:

tar xjf cascade-[package name].tar.bz2
cd cascade-[package name]
sudo ./installer -i

Just like on Windows, the installer will ask you a few configuration questions. See the Windows install instructions for details. The primary difference is that it won't ask for the CFS drive letter, since Unix systems do not have drive letters. Instead, the installer sets up CFS at /mnt/cfs.

The installer will:

CFS will be available immediately at /mnt/cfs after running the installer, without need for a reboot.

Make sure to keep around the installer script so you can uninstall Cascade later by typing sudo ./installer -u.

Set up Cascade Manager as a WSGI application

Assuming you already have Apache and mod_wsgi 2.x installed (see your Linux distribution's documentation for more information), add the following logic to your Apache httpd.conf:

WSGIScriptAlias /cascade /usr/local/bin/csc_manager.wsgi
WSGIPythonPath /usr/local/bin
WSGIPassAuthorization On
<Directory /usr/local/bin>
Order allow,deny
Allow from all
</Directory>

Then restart Apache with sudo /etc/init.d/apache2 restart.

Cascade Manager will now be available at http://hostname/cascade, or if you have mod_ssl installed, at https://hostname/cascade.

If you're using a web server other than Apache to host WSGI applications, consult your web server's documentation.

For Apache users, mod_wsgi 2.x is required. If you are using mod_wsgi 1.x, you must upgrade to 2.x before you can use Cascade Manager.

Run Cascade Worker service

You can start this service manually as follows. First, log in as cscwork. Then, to start it:

nohup csc_worker &

You can start multiple instances of Cascade Worker to run multiple tasks concurrently on a single machine; make sure to redirect their stdout to different files if you do this.

If you would like to run this service automatically at boot time, consult your Linux distribution's documentation to see how to add new services to your system's init scripts. Otherwise, if you don't reboot frequently, you can always start this service manually and leave it running.

Macintosh Installation Instructions

Check prerequisites

Set up user for Cascade Worker

If you intend to run this service, you will need to create a user account named cscwork for it to run with reduced privileges. You can do this from "System Preferences", "Accounts".

Upgrade pysqlite

Python 2.5.2 is bundled with pysqlite 2.3.2. If you are planning to host Cascade Manager off this machine, you should install pysqlite 2.5.0 or newer to pick up several important bug fixes. You can download the source distribution and find installation instructions at the pysqlite web site. If you don't upgrade pysqlite, you may encounter occasional hangs when multiple clients attempt to access the database concurrently.

If you are not hosting Cascade Manager off this computer, you can skip this step.

Run the installer

From whatever directory you like, type:

tar xjf cascade-[package name].tar.bz2
cd cascade-[package name]
sudo ./installer -i

Just like on Windows, the installer will ask you a few configuration questions. See the Windows install instructions for details. The primary difference is that it won't ask for the CFS drive letter, since Unix systems do not have drive letters. Instead, the installer sets up CFS at /mnt/cfs.

The installer will:

CFS will be available immediately at /mnt/cfs after running the installer, without need for a reboot.

Make sure to keep around the installer script so you can uninstall Cascade later by typing sudo ./installer -u.

Set up Cascade Manager as a WSGI application

See the Linux instructions above if you want to run Cascade Manager.

Run Cascade Worker service

To enable Cascade Worker, edit the file /Library/LaunchDaemons/csc_worker.plist. At the top of this file, you will find the following:

<key>Disabled</key>
<true />

Change true to false and save the file. This will cause the service to launch automatically every time the computer boots. To start the service immediately without a reboot, type:

sudo launchctl load /Library/LaunchDaemons/csc_worker.plist

Firewalls

Cascade Proxy uses port 4187. Make sure to unblock this port in your firewall on any computer you intend to use as a Cascade Proxy server. This port is officially registered with IANA as the csc_proxy service.

The default Windows version of Cascade Manager uses port 8080, the "HTTP Alternate" port for secondary web servers. Make sure to unblock this port in your firewall on any Windows computer where you install Cascade Manager, unless you are planning to set up the WSGI version of Cascade Manager to replace the default Windows version.

The WSGI version of Cascade Manager uses whichever port its web server is configured to listen on, usually port 80. Make sure to unblock this port in your firewall on any computer where you install Cascade Manager

Client-only installations and Cascade Worker installations do not require any firewall configuration changes. Because the Cascade Proxy server is built into Cascade File System, CFS will still attempt to listen for connections on port 4187 anyway. Most firewalls should block this port by default.

Windows WSGI Instructions

When you install Cascade Manager on Windows using the .msi installer, it sets up a self-contained, limited-functionality (e.g. no SSL support, no access logs) web server that runs on port 8080. This is adequate for simple usage, but if you would like to host Cascade Manager off a more powerful web server, you can use any WSGI-capable web server. These instructions assume that you want to use Apache.

Note that we have only tested the combination of Apache 2.2.9, Python 2.5.2, and mod_wsgi 2.3 with Cascade Manager on Windows. Versions of Python other than 2.5 will not work, and we recommend using 2.5.2 as many bugs have been fixed in this version. More recent patches of Apache and mod_wsgi ought to work but have not been explicitly tested. We do not recommend using older versions such as Apache 2.0; we recommend that you stick to Apache 2.2 if possible.

Install Cascade

Install Cascade as you would normally, making sure to enable the "Cascade Manager" and "Cascade File System" features in the installer. Verify that the standalone Cascade Manager web server works by pointing your web browser at http://localhost:8080/.

Install Apache

Download and run the Windows .msi installer for Apache 2.2.x from the Apache web site. The "Typical" install should work for most users.

To verify that Apache has been installed correctly, point your web browser at http://localhost/. It should display the text "It works!" in a large font.

Install Python

Download and run the Windows .msi installer for Python 2.5.x from the Python web site.

Apache is a 32-bit program, so even on 64-bit versions of Windows, you will need to install the 32-bit version of Python. It's OK if you already have the 64-bit version of Python installed—the two can coexist, as long as you install them to different directories. For example, if you already installed the 64-bit Python to the default location C:\Python25, you might install the 32-bit Python to C:\Python25_x86 or C:\Program Files (x86)\Python25.

Upgrade pysqlite

Python 2.5.2 is bundled with pysqlite 2.3.2. You should install pysqlite 2.5.0 or newer to pick up several important bug fixes. You can download an installer from the pysqlite web site. If you don't upgrade pysqlite, you may encounter occasional hangs when multiple clients attempt to access the database concurrently.

Install mod_wsgi

Download the Windows binary for mod_wsgi 2.3 from the mod_wsgi web site under the "Binaries (Windows)" link. Be careful to download the right binary; there is a separate binary for each version of Apache (2.0 vs. 2.2) and for each version of Python (2.4, 2.5). The file you want is simply named mod_wsgi.so, regardless of its version, so make sure to get the py25_apache22 version.

There is no mod_wsgi installer, but installing it is easy. Just copy this file into your (for example) C:\Program Files\Apache Software Foundation\Apache2.2\modules directory. If you are using a 64-bit version of Windows, remember that a 32-bit program like Apache will be installed to C:\Program Files (x86) by default, not C:\Program Files.

Then, add the following line to your Apache httpd.conf file, at the bottom of all the other LoadModule lines:

LoadModule wsgi_module modules/mod_wsgi.so

Add Cascade Manager entry to Apache conf file

Add the following lines to your httpd.conf, making changes to the paths if necessary based on where you installed Cascade. If you are using a 64-bit version of Windows, note that you will be pointing the 32-bit Apache at your 64-bit C:\Program Files\Conifer Systems\Cascade directory. This may seem odd, but it's not a problem—Apache will be running the portable Python bytecode, not the native binaries.

WSGIScriptAlias /cascade "C:\Program Files\Conifer Systems\Cascade\csc_manager.wsgi"
WSGIPythonPath "C:\Program Files\Conifer Systems\Cascade"
WSGIPassAuthorization On
<Directory "C:\Program Files\Conifer Systems\Cascade">
Order allow,deny
Allow from all
</Directory>

Once you have added Cascade Manager to your httpd.conf, restart Apache from the Apache Service Monitor, which it installs by default in your system tray.

To verify that Cascade Manager is accessible through Apache, point your web browser at http://localhost/cascade.

Disable the standalone Cascade Manager web server

We strongly recommend that you permanently disable the standalone Cascade Manager web server after setting up a WSGI server. Bring up the Services administrative tool and find the "Cascade Manager" service. Double-click on it to bring up its Properties. Hit the "Stop" button, then select "Startup type" of either "Manual" or "Disabled" and hit "OK".

Storage Size

At install time, Cascade will ask how much storage space in megabytes you want to devote to it. This storage will be preallocated from your hard drive and used internally by Cascade's caching subsystem. Files that you create or edit in a CFS tree will also be stored in this space. Make sure to allocate enough space for your typical working set, plus any files that you may edit or create. Remember that files you create as part of a build count towards this total, too.

If you decide you need more or less storage space later, you can destroy and rebuild your Cascade storage. Note that this involves wiping out your cache and all of your CFS trees, so make sure to to save and checkpoint or commit any work in progress before resizing your Cascade storage.

On Windows:

On Linux:

Upgrading an Existing Cascade Installation

Only a single version of Cascade can be installed on a single operating system at a time. If you want to run multiple versions of Cascade off the same PC at the same time, we recommend that you use virtualization to do so. There are several free virtualization products like VMWare Server and VirtualBox that will work.

Otherwise, if you want to install a new version of Cascade, you will first need to uninstall your existing version of Cascade.

The Windows .msi installer for Cascade automatically uninstalls the previous version of Cascade, so on Windows, you don't need to explicitly uninstall as a separate step. The installer will abort with an error if you try to install an older version than the currently installed version. However, if you really want to downgrade to an older version, you can still do by uninstalling the existing version first.

The Linux and Macintosh installer script will print an error message and ask you to uninstall first if they detect an existing installation.

We recommend that you restart Apache or any other web server hosting Cascade Manager after the upgrade, to ensure that the Cascade Manager scripts have been reloaded.

Network Protocol Compatibility

Cascade Proxy and Cascade Manager provide network services to Cascade clients (CFS, the Cascade command line client, the Cascade shell extension, Cascade Worker, and Cascade Proxy). The clients and servers must support the same network protocol in order for this to work.

Ideally, all clients and servers would be running the latest version of Cascade; we recommend that you upgrade at your earliest convenience. However, in practice, we understand that sometimes you will need to mix and match newer and older versions of the product on a single network.

Cascade 1.x is not protocol-compatible with Cascade 0.x. You will need to update any existing Cascade 0.x clients to 1.x if your servers are 1.x or newer.

Within the Cascade 1.x family, we intend to guarantee protocol backwards compatibility. That is, an older client ought to interoperate with a newer server. For Cascade 2.x and beyond, we expect to selectively retire server support for old 1.x protocol versions based on customer feedback.

We do not intend to guarantee protocol forwards compatibility. For example, we do not expect that a Cascade 1.0.1 or 1.0.2 client will interoperate correctly with a Cascade 1.0.0 server.

Cascade Cache File Format Compatibility

We do not presently guarantee any degree of compatibility between the cache file formats of any two different versions of Cascade. Upgrading Cascade involves wiping out the contents of your cache, and the installer will do this automatically as part of the uninstall. Upgrading CFS also involves wiping out your existing CFS trees; if you want to save the contents of your trees, you should checkpoint them first before upgrading, and clone a new tree from the checkpoint after the upgrade.

Cascade Manager Database File Format Compatibility

Cascade Manager keeps its state in an SQLite 3.x database. This database is typically stored at C:\Program Files\Conifer Systems\Cascade\Database (Windows) or /var/csc_manager (Linux or Macintosh). The SQLite database itself is a file called database. The files that comprise checkpoints and task results are stored separately in other files in this same directory.

The database file format is compatible between operating systems and CPUs. You can migrate a database between Windows, Linux, or Macintosh, or between 32-bit and 64-bit builds of Cascade, by simply copying the files. You should always shut down Cascade Manager first before attempting to copy these files; if Cascade Manager is writing to the database as you copy it, you may copy corrupted data.

We do not recommend that you manipulate the database directly, but SQLite 3.x includes a command-line client utility called sqlite3 that can examine and manipulate SQLite databases. You can use this command-line client's .dump command to take a snapshot of a live database without shutting down Cascade Manager first, e.g., to perform a hotcopy of the database to a backup. This dump is simply a sequence of SQL commands and can be replayed into a new SQLite 3.x database.

When you uninstall Cascade Manager, your existing database will not be deleted; our assumption is that, unlike the transient data in your cache, your Cascade Manager database contains important information that you want to preserve after the upgrade. (Warning: the Linux and Macintosh installer for Cascade 1.0.0 deletes the /var/csc_manager directory on uninstall, thereby wiping out your database. This installer bug has been corrected in Cascade 1.0.1. If you are upgrading from 1.0.0 to 1.0.1 on Linux or Macintosh and want to preserve the contents of your database, you should rename this directory first or copy its contents elsewhere.)

The Cascade Manager database schema is not compatible between Cascade 0.x and Cascade 1.x, and we do not provide an upgrade path. If you upgrade from Cascade 0.x, you will need to destroy your database and reconstruct a new one. You can do this by deleting all the files in the database directory after uninstalling the old version of Cascade.

For Cascade 1.x and beyond, we intend to change the database schema only on new minor versions, not new patches. For example, a database built using Cascade Manager 1.0.0 should continue to work unmodified on Cascade Manager 1.0.1. A database built using Cascade Manager 1.0.0 will not work with Cascade Manager 1.1.0. To upgrade your database to the latest file format, you will need to run the csc_db_upgrade program on the server where Cascade Manager is hosted. We recommend that you take a backup of the database first.

Of course, you are always free to destroy your existing Cascade Manager database on an upgrade, if you prefer. Again, you can do so by simply deleting all of the files.


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.