Pathway Tools Installation Guide -- Linux and MacOS X (Intel only)

The following instructions are for the supported UNIX systems, namely modern flavors of Linux x86, Linux x86_64, and MacOS X 10.4 and 10.5 (Intel only).

Note: Pathway Tools release 12.5 and later include libXm.so with the distribution, so installing OpenMotif should not be necessary.

Contents


Installing on MacOS X

IMPORTANT notes for MacOS X:

  1. Pathway Tools is known to run on MacOS X 10.4 and 10.5, both 32-bit and 64-bit, Intel only
  2. Our current installer is built on 32-bit MacOS 10.4. Because version MacOS X 10.5 changed some of its gadgets, the browse functionality will not work on MacOS X 10.5. Please install the software using the defaults. If you wish to move the pathway-tools folder to another place after installing, Pathway Tools will still work. However, the ptools-local data directory cannot be moved without reconfiguring the system. If its location should be inconvenient, please contact us for instructions on how to move it.
  3. These instructions assume that the optional X11 install has been performed. If not, it is on your installer disk. Open the Installer, select the X11 option, and follow the instructions given by the Installer.

    You can tell if you have X11 installed by clicking on the Finder menu Go->Utilities. You should see an entry for X11.

Step-By-Step Guide

  1. Decide where to install Pathway Tools. For a single user, your home directory is strongly recommended. This is the default location suggested by the installer. MacOS X 10.5 users must accept the installer's defaults for this release (13.0).
  2. Download the Pathway Tools distribution file. Safari users note: You must download the file with Control-Mouseclick, and select "Download Linked File" from the popup.

    These files are of the form

    pathway-tools-[version]-[platform]-[edition]-install
    where [version] is 13.0 for this release, [platform] is "macosx", and [edition] could be "collaborator", "nav-path-ed-tier1" and so on. An example would be
    pathway-tools-13.0-macosx-nav-ed-path-tier1-install

    The URLs pointing to these distributions can be found in the confirmation email that is sent after signing the license agreement. Please retain this email, as the same URLs will be used for every new release. Please also ensure that the correct distribution is selected for your specific platform.

  3. Bring up an X11 terminal window. This can be done by running the X11 utility and choosing Applications->Terminal.
  4. Ensure that the downloaded file is executable. Assuming the file was downloaded into your Desktop directory, issue the following command in the terminal window:

    chmod a+x Desktop/pathway-tools-13.0-macosx-nav-ed-path-tier1-install
  5. Execute the installer from the command line:
    Desktop/pathway-tools-13.0-macosx-nav-ed-path-tier1-install
  6. A GUI-based installer will guide you through the rest of the installation process. The installer will suggest you close all applications before continuing and give you the opportunity to cancel the installation.

    Click Next

  7. The installer will ask you where you want to install the Pathway Tools system. If you are running as a normal user, it will suggest a location in your home directory. If you are installing as the root user, it will suggest /usr/local/pathway-tools as a location. The latter is convenient if many users will be using Pathway Tools.

    Click Next once you have chosen a suitable location.

  8. Pathway Tools requires a directory where it will store local user data such as created PGDBs and HTML customization files. The installer will ask you to specify a directory path where Pathway Tools can create this "ptools-local" directory. Please make sure that all users who will update PGDBs have write permission to the ptools-local directory and its subdirectories. The default directory is the home directory of whoever is running the installer, which means that the data will reside in a directory called ~/ptools-local. MacOSX 10.5 users must accept the default for this release (13.0).

    IMPORTANT NOTE

    Do not install the ptools-local directory under your Pathway Tools installation directory, since the data in this directory would then be deleted when Pathway Tools is upgraded or reinstalled.

    Click Next once you have chosen a suitable location.

  9. The system will pop up a dialog describing the installation. If the information it gives is not suitable, you can click the Back button to revisit previous dialogs.

    Click Next to do the actual installation.

  10. Once the files are installed, the installer will pop up a pane reminding you of the location of the ptools-local directory. After a successful installation of Pathway Tools, a file with initialization parameters will have been written in this directory, retaining values from a prior installation if possible. The resulting file can be found in ptools-local/ptools-init.dat. This file may be customized and edited to define additional parameters specific to your site. Please see the Pathway Tools User Guide for more details on how to customize the ptools-init.dat file.

    Click OK.

  11. Click Finish to finish installing Pathway Tools. The installer will then pop up a banner saying that it is configuring Pathway Tools. This may take a minute or so depending on the speed of your computer. The installer will then exit.
  12. You may now run Pathway Tools as follows. If you've installed Pathway Tools in your home directory, there will be a script in the pathway-tools directory named pathway-tools. Invoke this script in the terminal window:
    ~/pathway-tools/pathway-tools

    This script may be copied into a location in your execution path for convenient use. For example, you could copy it into /usr/local/bin if you have that directory listed in your PATH environment variable. Then you could bring up Pathway tools by simply typing

    pathway-tools
    in an X11 terminal window.

Installing on Linux x86 or x86-64 (Intel / AMD)

Important Note For Linux: Please be sure that /bin/csh is present. Some current Linux distributions no longer install csh or tcsh by default. This will cause the installer to fail with a cryptic error message or even fail silently. Type
which csh
Your computer should respond:
/bin/csh

Step-By-Step Guide

  1. Decide where to install Pathway Tools. For a single user, your home directory is strongly recommended.

  2. Download the Pathway Tools distribution file. These files are of the form
    pathway-tools-[version]-[platform]-[edition]-install
    where [version] is 13.0 for this release, [platform] could be "linux" or "linux-64"", and [edition] could be "collaborator", "nav-path-ed-tier1" and so on. An example would be
    pathway-tools-13.0-linux-nav-ed-path-tier1-install
    If you are downloading the tier1-tier2-tier3 version of Pathway Tools for a 64-bit Linux machine, it will be in a tarball called ptools-linux64.tar.bz2. This distribution contains hundreds of organism-specific databases, and requires special installation instructions. Please proceed to the section
    "Installing Linux-64 BioCyc Tier1-Tier2-Tier3 Distribution".

    The URLs pointing to these distributions can be found in the confirmation email that is sent after signing the license agreement. Please retain this email, as the same URLs will be used for every new release. Please also ensure that the correct distribution is selected for your specific platform.

  3. The distribution files are executable installers. Run the file from the command line in the normal way:
    $ ./pathway-tools-13.0-linux-nav-ed-path-tier1-install

    You may need to first run

    $ chmod u+x pathway-tools-13.0-linux-nav-ed-path-tier1-install
    in order to make the file executable.

  4. A GUI-based installer will guide you through the installation process. First, it will ask you if you want to install Pathway Tools on your computer.

    Click Yes.

  5. The installer will suggest you close all applications before continuing and give you the opportunity to cancel the installation.

    Click Next

  6. The installer will ask you where you want to install the Pathway Tools system files. If you are running as a normal user, it will suggest a location in your home directory. If you are installing as the root user, it will suggest /usr/local/pathway-tools as a location. The latter is convenient if many users will be using Pathway Tools.

    If the suggested locations are not suitable, click on the Browse button to navigate to a more appropriate location.

    Click Next once you have chosen a suitable location.

  7. Pathway Tools requires a directory where it will store local user data such as created PGDBs and HTML customization files. The installer will ask you to specify a directory path where Pathway Tools can create this "ptools-local" directory. Please make sure that all users who will update PGDBs have write permission to the ptools-local directory and its subdirectories. The default directory is the home directory of whoever is running the installer, which means that the data will reside in a directory called ~/ptools-local. If you are installing for multiple users, a directory such as /var might be more appropriate.

    IMPORTANT NOTES

    Click Next once you have chosen a suitable location.

  8. The system will pop up a dialog describing the installation. If the information it gives is not suitable, you can click the Back button to revisit previous dialogs.

    Click Next to do the actual installation.

  9. Once the files are installed, the installer will pop up a pane reminding you of the location of the ptools-local directory. After a successful installation of Pathway Tools, a file with initialization parameters will have been written in this directory, retaining values from a prior installation if possible. The resulting file can be found in ptools-local/ptools-init.dat. This file may be customized and edited to define additional parameters specific to your site. Please see the Pathway Tools User Guide for more details on how to customize the ptools-init.dat file.

    Click OK.

  10. Click Finish to finish installing Pathway Tools. The installer will then pop up a banner saying that it is configuring Pathway Tools. This may take a minute or so depending on the speed of your computer. The installer will then exit.

  11. If you inadvertently skipped Oracle or MySQL configuration when you were visiting the previous web page, and you've decided to use a RDBMS, be sure to configure it now.
    [oracle configuration] [mysql configuration]

  12. Verify that Pathway Tools works by briefly running it (assuming it is installed in /usr/local/pathway-tools):
    /usr/local/pathway-tools/pathway-tools
  13. [Changed for release 13.0] To allow users to easily start up this program by simply typing pathway-tools, the script in the install directory can be copied into a location accessible by all users. Access as the root user is necessary for this step. Assuming the pathway-tools directory is located in /usr/local and user-accessible binaries in /usr/local/bin, execute the following command:
    rm -f /usr/local/bin/pathway-tools
    cp /usr/local/pathway-tools/pathway-tools /usr/local/bin/pathway-tools
    chmod 755 /usr/local/bin/pathway-tools
  14. Remote Access: Users often like to run Pathway Tools on a fast server and have the windows display on their desktop machine. For this to happen, the X server running on the desktop must allow remote connections.

    By default, most current versions of Linux do not configure the X Server to accept remote connections over the network. If you wish to run Pathway Tools on a server and have its windows show up on your local display, you must do one of the following.

    • Debian and Ubuntu systems need the string "-nolisten tcp" removed from all files in /etc/X11/ and its subdirectories in which the string occurs. Likewise for modern versions of Linux from the RedHat family, X Server security has been tightend. To get around this, the file /etc/X11/gdm/gdm.conf can be edited, to set:
      DisallowTCP=false
    • A different method around these X Server restrictions is to log into the computer with SSH using the -X flag (the -X flag enables forwarding X11 connections):
      ssh -X localhost
      Sometimes the -X argument will not work; in that case using -Y instead may work. For example, displaying Pathway Tools windows remotely on a Mac system seems to require the -Y argument. The -Y argument causes the forwarded connection to be "trusted".
      ssh -Y localhost
      Then, launch Pathway tools from within this session.

Installing Linux-64 BioCyc Tier1-Tier2-Tier3 Distribution

Due to limitations in our installer software, we use the old tarball method distribution of the full tier1-tier2-tier3 configuration.

This configuration contains more than 400 organisms and requires a large amount of memory. You will not be able to run this configuration unless you have at least 8Gb (eight gibabytes) of physical memory (RAM); more memory will be even better. Because of its large resource requirements, we do not recommend you use this configuration unless you require access to large numbers of organism databases. Note that you can download individual organism databases from the PGDB registry and add them to a tier1 or tier1-tier2 configuration that does not have very large memory requirements.

Follow these instructions to install:

  1. Determine where you wish to install the software. At least 15 Gb of disk space is required to unpack this software.
  2. Save the distribution file into a convenient directory (here or elsewhere).
  3. Change directory to the place where you wish to install the software.
  4. Extract the distribution:
    tar jxvf *path to tarball*
  5. Run the configuration command:
    ./aic-export/pathway-tools/ptools/13.0/install/config-ptools
    This will ask you for the location of the "ptools-local" directory. If you are installing for many users, the /var directory might be a suitable place for this directory. If you are installing for a single user, that user's home directory might be appropriate.
    Enter pathname of Pathway Tools local directory: /homedir/gilham
  6. See this item in the instructions above for instructions on creating a script for easy execution of Pathway Tools.
Once the software exits the configuration step, your system will be ready for use.

For All Users and All Distributions

The Pathway Tools User's Guide documents the many ways you can configure the ptools-init.dat file to run Pathway Tools (including as a web server). That document is available within the Pathway Tools "Help" menu and for this release (13.0) is stored at:
pathway-tools/aic-export/pathway-tools/ptools/13.0/doc/manuals/UserGuide.pdf