Return to main table of contents
Windows:
Linux:
Macintosh:
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.
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:
Cascade Manager URL: Typically this will be 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 intend to run Cascade Manager off your own local
Windows desktop, hostname is simply your own computer's
hostname.
Cascade Proxy hostname: Enter the hostname of the computer running Cascade Proxy. If you aren't using a proxy server, you can leave this blank.
Important: never set this field to localhost, or to this
computer's own hostname or IP address. Always point it either at another
computer, or leave it blank. Do not set up proxies in a circular chain: for
example, if you tell computer A to use computer B as a proxy, and tell computer
B to use computer A as a proxy, this will not work.
Cascade File System drive letter: The default X: is
fine as long as you're not already using the X: drive for something else. You
can set it to any unused drive letter.
Megabytes of disk space to reserve for Cascade: The default is probably OK for most users. See detailed discussion under "Storage Size".
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.
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.
glibc 2.3: Type /lib/libc.so.* to check what version you
have. The first line printed should list the glibc version number. If your
glibc is older than 2.3, you will need to upgrade to a newer Linux
distribution.
Python 2.5 (2.5.2 recommended): Type python2.5 -V to check
whether you have Python 2.5. If you have Python 2.5, it will print the version
number, e.g., "Python 2.5.2" and exit. If you don't, it will print an error
message. Python 2.6 is not entirely compatible with Python 2.5, so it is not
sufficient to have Python 2.6 installed. (Note that multiple versions of Python
can coexist on a single operating system.) Python 2.5 or 2.5.1 may work, but
many bugs have been fixed in 2.5.2 and so we recommend using 2.5.2 if possible.
If you don't have Python 2.5, you can probably obtain a package for it from your
Linux distribution (check your Linux distribution's documentation for details).
If you can't upgrade through your distribution, you can always download the
sources from the Python web site and
compile and install Python yourself.
fuse 2.7: Type fusermount -V to check what version you have,
if any. This module is provided with many modern distributions, but it's
possible that your distribution does not include FUSE. If you can't obtain
FUSE through your distribution, you can build and install it from source at
the FUSE web site.
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.
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.
Edit the file /etc/fuse.conf and uncomment the line
user_allow_other by removing the # in front of it. If
/etc/fuse.conf does not exist, you can ignore this step.
Edit the file /etc/updatedb.conf and add the text
fuse.cfs_fuse to the PRUNEFS string. This is,
strictly speaking, optional, but it's generally undesirable for the
locate service to attempt to index CFS.
From whatever directory you like, type:
tar xjf cascade-[package name].tar.bz2
cd cascade-[package name]
sudo ./installer -iJust 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:
cscwork user for Cascade Worker/etc/cascade.conf configuration file/mnt/cfs,
/var/cfs, and /var/csc_manager directories/usr/local/bin and
/usr/local/lib/etc/fstab so that CFS is automatically mounted
at boot timeCFS 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.
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.
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.
x86-based CPU (not PowerPC): Type uname -p at the Terminal
to check what CPU you have. If it prints i386, you have an
x86-based Mac.
Mac OS X 10.4 ("Tiger"): Tiger was the first Mac OS X release to support x86 CPUs, so you shouldn't need to explicitly verify this.
Python 2.5 (2.5.2 recommended): Type python2.5 -V to check
whether you have Python 2.5. If you have Python 2.5, it will print the version
number, e.g., "Python 2.5.2" and exit. If you don't, it will print an error
message. Python 2.6 is not entirely compatible with Python 2.5, so it is not
sufficient to have Python 2.6 installed. (Note that multiple versions of Python
can coexist on a single operating system.) Mac OS X 10.4 ("Tiger") shipped with
Python 2.3, while Mac OS X 10.5 ("Leopard") shipped with Python 2.5.1. If you
are running Leopard, you should be fine, although you may wish to consider an
upgrade from 2.5.1 to 2.5.2, as many bugs have been fixed in 2.5.2. If you are
running Tiger and have not already upgraded to Python 2.5, you can download an
upgrade here.
MacFUSE 1.7: You can download the latest MacFUSE installer under "Featured Downloads" at the MacFUSE web site. Recent versions of MacFUSE contain an automatic update feature, so once you've installed MacFUSE, it should automatically keep itself updated.
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".
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.
From whatever directory you like, type:
tar xjf cascade-[package name].tar.bz2
cd cascade-[package name]
sudo ./installer -iJust 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:
/etc/cascade.conf configuration file/mnt/cfs,
/var/cfs, and /var/csc_manager directories/usr/local/bin and
/usr/local/libCFS 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.
See the Linux instructions above if you want to run Cascade Manager.
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.plistCascade 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.
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 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/.
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.
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.
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.
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.soAdd 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.
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".
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:
regeditHKEY_LOCAL_MACHINE\Software\Conifer Systems\Cascade
registry key.CFS_STORAGE_SIZE_MB.net stop cfs_ntcfs_storage file in the directory where you
installed Cascade.net start cfs_ntOn Linux:
CFS_STORAGE_SIZE_MB in /etc/cascade.confsudo fusermount -u /mnt/cfssudo rm /var/cfs/storagesudo mount /mnt/cfsOnly 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.
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.
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 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.