Cascade 1.0.0.769 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. Install compatibility libraries
    3. Configure FUSE
    4. Run the installer
    5. Set up Cascade Manager as an Apache/mod_python module
    6. Run Cascade Proxy and/or Cascade Worker services
  5. Macintosh Installation Instructions
    1. Check prerequisites
    2. Set up users for Cascade Proxy and/or Cascade Worker
    3. Run the installer
    4. Set up Cascade Manager as an Apache/mod_python module
    5. Run Cascade Proxy and/or Cascade Worker services
  6. Firewalls
  7. Windows Apache/mod_python Instructions
    1. Install Cascade
    2. Install Apache
    3. Install Python
    4. Install mod_python
    5. Add Cascade Manager entry to Apache conf file
    6. Disable the standalone Cascade Manager web server
  8. Storage Size

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 Proxy or 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 can run Cascade Proxy and Cascade Manager off the same PC. This is probably the simplest way to set things up if you only intend to use one proxy.

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

Install compatibility libraries

Cascade for Linux is built against fairly old (Red Hat Linux 9 for x86, CentOS 3.9 for x86_64) Linux distributions, in order to increase the number of Linux distributions that Cascade will run on. Unfortunately, some libraries have undergone non-backwards-compatible changes since then, and newer distributions often do not install older libraries by default.

On newer Red Hat-derived distributions (includes Fedora and CentOS), type:

sudo yum install compat-libstdc++-33

On newer Debian-derived distributions (includes Ubuntu), type:

sudo apt-get install libstdc++5

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 after running the installer at /mnt/cfs, 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 an Apache/mod_python module

Assuming you already have Apache and mod_python installed, add the following logic to your Apache httpd.conf:

<Location /cascade>
  SetHandler mod_python
  PythonHandler csc_manager_modpy
  PythonPath "sys.path + ['/usr/local/bin']"
  PythonOption UrlPrefix /cascade
  PythonDebug On
</Location>

(PythonDebug On is optional but recommended for more detailed error messages.)

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.

Run Cascade Proxy and/or Cascade Worker services

You can start these services manually as follows. First, log in as the desired user, cscproxy or cscwork. Then, to start Cascade Proxy:

nohup csc_proxy &

To start Cascade Worker:

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 these services 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 these services manually and leave them running.

Macintosh Installation Instructions

Check prerequisites

Set up users for Cascade Proxy and/or Cascade Worker

If you intend to run either of these services, you will need to create user accounts named cscproxy and cscwork for them to run with reduced privileges. You can do this from "System Preferences", "Accounts".

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 after running the installer at /mnt/cfs, 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 an Apache/mod_python module

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

Run Cascade Proxy and/or Cascade Worker services

To enable Cascade Proxy or Cascade Worker, edit the files csc_proxy.plist and csc_worker.plist in /Library/LaunchDaemons/. At the top of each file, you will find the following:

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

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

sudo launchctl load /Library/LaunchDaemons/[filename].plist

...where [filename] is either csc_proxy or csc_worker.

Firewalls

Cascade Proxy uses port 4187 by default. Make sure to unblock this port in your firewall on any computer where you install Cascade Proxy. 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 Apache/mod_python version of Cascade Manager to replace the default Windows version.

The Apache/mod_python version of Cascade Manager uses whichever port Apache 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 listen on any ports and therefore do not require any firewall configuration changes.

Windows Apache/mod_python 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 mod_python off a more powerful web server, you can use Apache.

Note that we have only tested the combination of Apache 2.2, Python 2.5, and mod_python 3.3 with Cascade Manager. Versions of Python earlier than 2.5 will not work. Other versions of Apache and mod_python may work but have not been tested; we recommend that you stick to Apache 2.2 and mod_python 3.3 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 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 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.

Install mod_python

Download and run the Windows installer for mod_python 3.3 from the mod_python web site. Be careful to download the right installer; there is a separate installer for each version of Apache (2.0 vs. 2.2) and for each version of Python (2.3, 2.4, 2.5). The installer you want will be named something like mod_python-3.3.?.win32-py2.5-Apache2.2.exe, where ? is the latest patch level for mod_python 3.3.

The mod_python installer will ask you where you installed Apache. You will need to point it at the (for example) C:\Program Files\Apache Software Foundation\Apache2.2 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.

When the mod_python installer completes, it will ask you to add the line LoadModule python_module modules/mod_python.so to your Apache httpd.conf file. Make the requested change.

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 and based on your CFS drive letter. 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.

<Location /cascade>
  SetHandler mod_python
  PythonHandler csc_manager_modpy
  PythonPath "sys.path + ['C:\Program Files\Conifer Systems\Cascade']"
  PythonOption UrlPrefix /cascade
  PythonDebug On
</Location>

(PythonDebug On is optional but recommended for more detailed error messages.)

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 the Apache/mod_python 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 CFS. This storage will be preallocated from your hard drive and used internally by CFS'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 CFS 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 CFS storage.

On Windows:

On Linux:


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.