$Id: INSTALL,v 1.29 2006/04/21 14:52:38 schapira Exp $ You must install two components to run Proximity: - a Proximity client - a MonetDB server (the database back-end for Proximity) This document describes how to download and install both of these components. Proximity 4.2 operates with MonetDB 4.6.2 and later versions. Users updating from Proximity 4.0 or later versions need only install the updated Proximity client. Proximity 4.2 requires no change to the underlying MonetDB database. Users updating from Proximity 3.1 or earlier must also update their MonetDB installation and update their databases. See "Re-using MonetDB databases in MonetDB 4.6" and "Proximity schema updates" later in this document for additional information on updating from Proximity 3.1. [Note that starting with MonetDB 4.8, MonetDB tables are incompatible with earlier versions. Proximity 4.2 users can continue to use MonetDB 4.6.2 (provided with the current release) or update to MonetDB 4.8 (available from CWI at monetdb.cwi.nl) and recreate their databases. Proximity databases can be recreated in MonetDB 4.8 by exporting existing databases as XML and importing the XML into the new database.] --------------------------------------------------------- | Proximity 4.2 is NOT yet fully compatible with the | | latest release of MonetDB, 4.10.2. | --------------------------------------------------------- In addition to this file, please see the README file for additional information including: - importing Proximity 2 databases into Proximity 4.2 - subscribing to Proximity mailing lists - requesting technical support - reporting bugs ====================================================================== Client (Proximity) installation ====================================================================== Note: Since version 4.1, the Proximity client changes the root Proximity directory from "proximity3" to "proximity." The Proximity client requires Java 2 Platform, Standard Edition, v1.4.2 (J2SE) or later. To install the Proximity client, follow these steps: 1. Download the Proximity client distribution. 2. Extract the tarball to the desired location. On Unix-based systems, use the tar command: $ tar xvfz ~/proximity-4.2.tgz (the actual name of the file will vary depending on the version number) You must use a version of tar (e.g., GNU tar) that supports long filenames. On Windows, unpack the file with WinZip or an equivalent application. 3a. On Unix-based systems, change the permissions of the bin/ directory with the following command: $ cd proximity/ $ chmod -R a+x bin/ 3b. On Windows systems, set the PROX_HOME environment variable to the Proximity installation directory. For example, if you have installed Proximity in C:\Proximity\, then you would set PROX_HOME=C:\Proximity\ The way you set this variable will vary depending on your version of Windows. To get started using Proximity, see the tutorial in either - proximity/doc/user/tutorial/Tutorial.pdf - proximity/doc/user/tutorial/HTML/index.html ====================================================================== Server (MonetDB) installation ====================================================================== In order to run the Proximity client you need to install the MonetDB server. Follow the instructions below for installing MonetDB for Unix-style platforms (including Mac OS X) or Windows. a) Instructions for Unix-style platforms: ----------------------------------------- You must have administrator privileges to install MonetDB; log in as root (Unix/Linux) or use sudo (Mac). 1. Download the binary distribution for your platform from our website. This distribution includes MonetDB documentation. 2. Extract the tarball to your /usr/local/ directory. (NOTE: this binary distribution of MonetDB is not relocatable!) $ cd /usr/local $ tar xvfz ~/monet-4.6.2-distr-[mac|linux].tgz 3. Change the permissions of the var/ directory with the following command (also requires administrator privileges): $ cd Monet-46/ $ chmod -R a+w var/ Start the MonetDB server with the following command: $ /usr/local/Monet-46/bin/Mserver You can optionally add /usr/local/Monet-46/bin to PATH. Running the server without specifying a database connects to the demo database. To start the server on a particular database, use the following command: $ Mserver --dbname /resources/init-mserver.mil where is the database name and is the location of your local Proximity installation. Quit the MonetDB server with MonetDB> quit(); where "MonetDB>" is the Monet server prompt and "quit();" is the command (note the parentheses and semi-colon) See the Proximity tutorial for additional information on using the MonetDB server for Proximity. MonetDB documentation is available in /usr/local/Monet-46/doc/. b) Instructions for Windows platforms: -------------------------------------- The Windows MonetDB distribution requires Windows Professional 2000 or later. 1. Download the binary Windows installer (Zip file) from our website. 2. Unpack the installer files from the Zip archive with WinZip or an equivalent application. 3. As an administrator, run the Microsoft installer for MonetDB, MonetDB-installer-4.6.2.msi, by double-clicking the file name to start the installation wizard. Follow the instructions to install the server in the desired location. The default installation directory is C:\Program Files\CWI\MonetDB. Proximity does not require the MonetDB ODBC driver. You can unselect this option on the third page of the installation wizard if you only plan to use MonetDB to serve Proximity databases. You can ignore warnings that "installation will fail if this component is not installed" if you are not installing the MonetDB ODBC driver; this warning refers to installing the MonetDB ODBC driver without having other required software already installed. The choice of installing MonetDB for "Just me" or "All users" affects only whether MonetDB is added to the Start Menu for the current user or for all users. In all cases, MonetDB stores its databases in C:\\Documents and Settings\\Application Data\MonetDB\dbfarm\ where is the name of the current user. 4. As an administrator, run Mserver.bat (located the installation directory). This creates the required directory hierarchy for MonetDB databases. 5. Quit the MonetDB server with MonetDB> quit(); where "MonetDB>" is the MonetDB server prompt and "quit();" is the command (note the parentheses and semi-colon) 6. Unpack the MonetDB documentation files in monet-4.6.2-docs.zip (included in the Windows MonetDB distribution) to your MonetDB installation directory. This creates a 'doc' directory in your installation directory. The MonetDB server is run from the command (DOS) window. Start the MonetDB server with the following command (substitute the appropriate path if you installed the server someplace other than the default location): > "C:\Program Files\CWI\MonetDB\Mserver.bat" You can optionally add the MonetDB installation directory to PATH. You may need to restart your command window to have this update available. Running the server without specifying a database connects to the demo database. To start the server on a particular database, use the following command (all on one line): > "C:\Program Files\CWI\MonetDB\Mserver.bat" --dbname "\resources\init-mserver.mil" where is the database name and is the location of your local Proximity installation. Quit the MonetDB server with MonetDB> quit(); See the Proximity tutorial for additional information on using the MonetDB server for Proximity. MonetDB documentation is available in the 'doc' directory under your local MonetDB installation directory. ====================================================================== Re-using MonetDB databases in MonetDB 4.6: ====================================================================== -------------------------------------------------------------------- | Users updating from Proximity 4.0 or later are not required to | | update existing databases and can safely ignore this section. | -------------------------------------------------------------------- Updating to Proximity 4.2 from Proximity 3.1 or earlier includes a required update to the MonetDB installation and a required conversion of existing databases to the new MonetDB format. Proximity 4.2 requires MonetDB 4.6 (MonetDB 4.6.2 includes important bug fixes and is recommended). Location of database files: --------------------------- MonetDB 4.6 stores database files in a different directory than that used by earlier versions of MonetDB. - Linux and Macintosh users should copy existing MonetDB databases to the new location to use them in MonetDB 4.6. You must have administrator privileges to make these changes. Copying all databases: > cd /usr/local/Monet-46/var/MonetDB/dbfarm > cp -R /usr/local/Monet/var/MonetDB/dbfarm/* . - The Windows installation of MonetDB 4.6 automatically moves any existing database files to the new location: C:\\Documents and Settings\\Application Data\MonetDB\dbfarm where is the login name of the user who installed MonetDB. Backward compatibility: ----------------------- Databases converted to MonetDB 4.6 may not be usable in older versions of MonetDB. We recommend that you backup any database that you might want to use in an older version of MonetDB before converting it to MonetDB 4.6. Updating databases: ------------------- The first time you serve an existing database with MonetDB 4.6, you must commit the database to bring the BAT buffer pool (BBP) up to date. 1. Serve the database. > Mserver --dbname MonetDB prints an error message indicating that the BBP is out of date: !WARNING: old BBP without size indications: assuming compatible with current server !WARNING: if this assumption is not correct, quit() immediately! !WARNING: otherwise, first commit() to write a new BBP You may also see a message indicating that MonetDB has moved the database file. 2. Enter "commit();" to commit the database and correct the BBP. 3. Enter "quit();" to quit the MonetDB server. ====================================================================== Proximity schema update ====================================================================== -------------------------------------------------------------------- | Users updating from Proximity 4.0 or later are not required to | | update existing databases and can safely ignore this section. | -------------------------------------------------------------------- Updating to Proximity 4.2 from Proximity 3.1 or earlier includes a required update to database schema version 1.6. This update simplifies code and improves performance. You must update the schema for any existing databases before using them in Proximity 4.2 You can confirm the current schema version number of a database by running the dbutil script with the schema option: Getting the schema version number under Linux/Mac OS X: ------------------------------------------------------- 1. Make sure you are serving the database using Mserver. 2. Run the dbutil.sh script. Substitute the appropriate host and port number if you are running the MonetDB server on a different machine or using a different port. > cd $PROX_HOME > bin/dbutil.sh localhost:45678 schema Getting the schema version number under Windows: ------------------------------------------------ 1. Make sure you are serving the database using Mserver. 2. Run the dbutil.bat script. Substitute the appropriate host and port number if you are running the MonetDB server on a different machine or using a different port. > cd %PROX_HOME% > bin\dbutil.bat localhost:45678 schema To make the schema change, stop serving the database (if it is currently running), then restart the MonetDB server on that database and include the schema conversion script in the Mserver command line as described below. You only need to run the schema conversion script once for each database. Changing the schema for Linux/Mac OS X: --------------------------------------- 1. Make sure you are not currently serving the database. If necessary, quit the MonetDB server with > quit(); 2. Serve the database using both the standard init-mserver.mil script and the schema conversion script. > Mserver --dbname \ $PROX_HOME/resources/init-mserver.mil \ $PROX_HOME/resources/schema-1.5-to-1.6.mil where is the name of the existing database. The order of MIL scripts is important; you must place init-mserver.mil before schema-1.5-to-1.6.mil on the command line. When successful, the script reports "Conversion complete." Running the script on an already-converted database is harmless. If the database has the correct schema, the script reports "Database schema is up-to-date." Changing the schema for Windows: -------------------------------- 1. Make sure you are not currently serving the database. If necessary, quit the MonetDB server with > quit(); 2. Serve the database using both the standard init-mserver.mil script and the schema conversion script. > Mserver --dbname \ %PROX_HOME%\resources\init-mserver.mil \ %PROX_HOME%\resources\schema-1.5-to-1.6.mil where is the name of the existing database. The order of MIL scripts is important; you must place init-mserver.mil before schema-1.5-to-1.6.mil on the command line. When successful, the script reports "Conversion complete." Running the script on an already-converted database is harmless. If the database has the correct schema, the script reports "Database schema is up-to-date."