====== Installing the Trio System======


===== Package Overview =====

The Trio system is implemented in the Python programming language and layered on top of the PostgreSQL open-source DBMS. The system comes shipped with two user interfaces: ''trioplus'', a command-line interface (CLI), and ''TrioExplorer'', a web-based GUI with user-friendly control features, help pages, and some sample applications and queries. Trio also includes a basic Application Programming Interface (API) similar to the [[http://www.python.org/dev/peps/pep-0249/ | Python DB-API]] specification, on which the user interfaces are built.

The complete Trio functionality is available through the Python implementation, including a TriQL grammar parser and a hierarchical rewriting architecture that creates standard SQL queries from TriQL, which are then executed over a relational encoding of our data structures. Only a few complex operations such as on-demand lineage traversal and confidence computation are implemented as stored procedures.

The core functionality such as data-intensive fetch operations and cursor management are implemented redundantly in Python and a precompiled C-code library extension using the PostgreSQL-specific Server Programing Interface (SPI) to achieve better performance. However, the current release only contains slower Python implementation. If you are interested in performance experiments, please contact us!

In its default configuration, the Trio system requires the following software packages:

  * [[http://www.python.org/ | Python ]] Programming Language (version 2.4 or higher)
    * The Python interpreter is used to execute both ''trioplus'' and ''TrioExplorer''.

  * [[http://www.postgresql.org/ | PostgreSQL]] (version 8.2 or higher)
    * The underlying relational DBMS.

  * [[http://www.graphviz.org/ | Graphviz]]
    * A graph visualization tool to render schema graphs in ''TrioExplorer''.

Currently we are running the system successfully on Linux, Mac OS X, and Windows XP/Vista.


===== Installation Instructions =====




==== Installing Peripheral Packages ====

  - **Python** (version 2.4 or higher)
    * Most Linux distributions and Mac OS X Leopard have Python installed.
    * Please note that Trio is not tested with Python 3.0.
    * For Linux, install Python using a software package manager (e.g., ''apt-get'' or ''yum'').
    * For Mac OS X, installer is available at ''http://www.python.org/download/''.
    * For Windows, installer is available at ''http://www.python.org/download/''.
        * Don't install version 2.6 because ''Easy Install'' doesn't have a windows installer for Python 2.6 yet.
    * Make sure Python's ''bin'' directory (e.g., ''C:\Python25;C:\Python25\Scripts'') is in your ''PATH'' environment (by running ''python -V'').
  - **PostgreSQL** (version 8.2 or higher)
    * For Linux, install PostgreSQL using a software package manager (e.g., ''apt-get'' or ''yum'').
    * For Mac OS X, installers are available at ''http://www.postgresql.org/download/macosx''.
    * For Windows, pgInstaller is available at ''http://www.postgresql.org/ftp/binary/v8.2.11/win32/''.
        * Don't install version 8.3 because ''triospi.dll'' for PostgreSQL 8.3 is not provided.
    * Make sure PostgreSQL's ''bin'' directory (e.g., ''C:\Program Files\PostgreSQL\8.2\bin'') is in your ''PATH'' environment (by running ''postgres -V'' and ''pg_config'').
        * In some distributions, ''pg_config'' is in the development package. We recommend installing ''pg_config'' because it will detect the correct location of ''triospi.so'' or ''triospi.dll''.
    * Make sure ''plpgsql'' support is enabled.
        * For Windows and Mac OS X, installer does it for you by default.
        * For Linux, please see [[http://www.postgresql.org/docs/8.3/static/creating-cluster.html | Creating a Database Cluster]] and [[http://www.postgresql.org/docs/8.3/static/server-start.html | Starting the Database Server]] to start PostgreSQL. Then, run ''**createlang plpgsql template1**'' to enable ''plpgsql'' for newly created databases.
    * If you are going to running PostgreSQL using an account other than ''postgres'', you need to create a database with the account name (e.g., run ''createdb trio''). Please refer to [[http://www.postgresql.org/docs/8.3/static/postgres-user.html | The PostgreSQL User Account]] and [[http://www.postgresql.org/docs/8.3/static/creating-cluster.html | Creating a Database Cluster]].
  - **Graphviz**
    * For Linux, install Graphviz using a software package manager (e.g., ''apt-get'' or ''yum'').
    * For Mac OS X and Windows, executable packages are available at ''http://www.graphviz.org/Download.php''.
    * Make sure Graphviz's ''bin'' directory (e.g., ''C:\Program Files\Graphviz 2.21\bin'') is in your ''PATH'' environment (by running ''d

t -V'').



==== Installing Trio ====

Depending on the environment, you might need root privileges to complete these steps.
  - Install ''[[http://peak.telecommunity.com/DevCenter/EasyInstall | Easy Install]]''. Please see ''http://pypi.python.org/pypi/setuptools'' for instructions.
  - //For Windows only//, install ''PyGreSQL'' win32 package at ''http://www.pygresql.org/readme.html#download-pygresql-here'' (Installing ''PyGreSQL'' with ''Easy Install'' requires the Microsoft Visual C++).
  - Run ''**easy_install -U -f http://''''infolab.stanford.edu/trio/code/ Trio TrioExplorer**'' to install Trio packages and all required libraries.
  - Run ''**triospi_install**'' to get the SPI module working.
    * This step will fail if you don't have ''pg_config''. You can manually do this step by copying ''site-packages/Trio-1.1-py2.5.egg/trio/spi/{linux2|darwin|win32}/pg-{8.2|8.3}/triospi.{so|dll}'' into PostgreSQL's ''lib'' directory (e.g., ''/usr/lib/pgsql'' or ''C:\Program Files\PostgreSQL\8.2\lib''). ''site-packages'' is usually in ''/usr/lib/python2.5'' or ''C:\Python25\Lib''.


====== Running the Trio System ======

==== TrioExplorer ====

Preparing ''TrioExplorer'' for its first use requires generating ''trioexplorer.ini''. Please run ''**paster make-config TrioExplorer trioexplorer.ini**'' inside a directory of your choice (e.g., ''C:\Trio'' or ''~/Trio''). While running ''TrioExplorer'', some temporary files will be generated as well in the directory.
  - Make sure PostgreSQL is working.
  - Running ''TrioExplorer''
    * Run ''**paster serve trioexplorer.ini**''
    * For Linux and Mac OS X, daemon mode is available: run ''paster serve -''''-daemon trioexplorer.ini'' and ''paster serve -''''-stop-daemon'' to start and stop TrioExplorer. Please run ''paster serve -h'' for more options.
    * If you are prompted for a DBA login to PostgreSQL, please provide one created along with your PostgreSQL installation (e.g., ''postgres'').
  - ''TrioExplorer'' should now be reachable from your browser, e.g., using ''http://127.0.0.1:8080/'' or ''http://localhost:8080/''.

==== trioplus ====

Preparing ''trioplus'' for its first use requires a new user role and database instance be installed manually (denoted in the following as ''foo'' and ''bar''), which should be different from the default PostgreSQL instance, and which requires logging in onto the PostgreSQL server with admin privileges (denoted in the following by the admin user name ''postgres''). 

If you already have created a user login and database instance under ''TrioExplorer'', you may just skip this step and directly jump to the last bullet, i.e., run ''trioplus -u foo -d bar -p''.
  - Create your new PostgreSQL user role and database instance using the following PostgreSQL executables:
    * Run ''createuser [-U postgres] -S -D -R -P foo''
    * Run ''createdb [-U postgres] -O foo bar''
    * Note that for each of the above commands you might need to explicitly login as a superuser, if your default PostgreSQL user name is not a trusted PostgreSQL user, e.g., using ''createuser -U postgres foo''.
  - Set up some Trio metadata and initialize the Trio schema information for this new user:
    * Run ''triosetupdb [-U postgres] bar foo''
  - Connect to your new Trio database using the command line client:
    * Run ''trioplus -u foo -d bar -p''