MARIPOSA (alpha-1) INSTALLATION INSTRUCTIONS
Copyright (c) 1996 Regents of the University of California

This directory contains the source and documentation for Mariposa
(version alpha-1)  Mariposa is based on an early version of
Postgres95, which in turn is a derivative of POSTGRES 4.2
(the last release of the UC Berkeley research project).
For copyright terms for Mariposa, please see the file named COPYRIGHT.  
Mariposa is a product of the Mariposa research group, led by
Prof. Mike Stonebraker; Postgres95 was developed by Jolly Chen and
Andrew Yu. 

Mariposa alpha-1 is currently supported on the following platform:

 *  Digital Equipment Alpha running DEC OSF/1 3.2 (with gcc and cc).

More platforms will be added in subsequent releases.

You should have at least 8 MB of memory and at least 50 MB of disk space to
hold the source, binaries, and user databases.

----------------------------------------------------------------------
To install Mariposa on UNIX platforms:

1. Create the mariposa login.
   
   Create a login called mariposa (this requires root privileges). We 
   recommend that you run the sitemanager as the user mariposa for security 
   reasons.

   If you run the sitemanager as yourself, be warned that you essentially
   grant all database users the ability to execute arbitrary C functions
   as you without your password. (In any case, DO NOT run the sitemanager
   as root.)

2. Compile and install Mariposa.

   If you have any versions of Postgres installed, you will want
   to install Mariposa in a different place.

   Our Makefiles require GNU make (called gmake in this document) and
   also assume that "install" accepts BSD options. The INSTALL
   variable in the Makefiles is set to the BSD-compatible version of
   install. On some systems, you will have to find a BSD-compatible
   install to use as the value for this variable. (e.g. bsdinst, which
   comes with the MIT X Window System distribution) 

   Customization can be done by editing src/Makefile.global. You may change
   the various configuration options here, such as where the Mariposa
   executable files are installed and where the system looks for the database
   directory.  The configuration switches are fairly self-explanatory, but we
   will go over some of the more commonly-changed options:

     -  PORTNAME specifies the platform on which Mariposa is being built
        (alpha is the only option for this release).

     -  POSTGRESLOGIN specifies the user who will be doing initdb and
        running the sitemanager (defaults to mariposa).  Do not set
        this to root, or any users with UID = 0!

     -  POSTGRESDIR specifies the top-level directory where Mariposa
        binaries, header files, libraries, and databases are installed.

     -  SRCDIR specifies where the source files are located. (defaults
        to $(POSTGRESDIR)/src.)

2a. Set up your environment.

   The alpha-1 release requires a script called 'unravel' that
   lives in $(srcdir)/bin.  (For example, /private/mariposa/src/bin)
   Make sure this script is in your PATH, and that the first line
   of the script points to the Perl executable for your system.
   (Its default value is #!/usr/sww/bin/perl)

2b. Build.

   After editing src/Makefile.global, you are ready to compile and
   install Mariposa (it takes about 40 minutes on a 150Mhz Alpha
   running OSF/1 3.2):

     % cd src
     % which unravel
     (prints location of unravel -- if not, make sure it's in your PATH)
     % gmake install

   After the installation is complete, check that you have the following files
   in the top level Mariposa directory (e.g. /private/mariposa).

   You will find the following executables in the bin directory (which
   should be included in the search path of your shell):

     % ls /private/mariposa/bin
     cleardbdir*   destroyuser*  mp_hostaddr*  psql*
     createdb*     initdb*       pg_id*        siteinstall*
     createuser*   initmp*       pg_version*   sitemanager*
     destroydb*    monitor*      postgres*     siteplan*


   You will find the following in the database directory:

     % ls -R ../data
     files/

     ../data/files:
     bidder.tcl                    local1_template1.bki
     databroker.tcl                local1_template1.bki.source
     global1.bki                   rules.tcl
     global1.bki.source

3. Plan your installation.

   There are a few options for running Mariposa.  A user
   can run Mariposa as a single-site database, as multiple
   "sites" on the same machine, or as a distributed system
   across two or more machines.  We will address the last case
   first.

4. Multi-site setup.

   To create a multi-site system, first make sure that the
   the Mariposa bin directory is in your PATH.  'cd' into 
   the bin directory.

   Next, make sure that the Perl scripts 'siteplan' and 'siteinstall'
   are set up to find the correct Perl executable.  (Current
   default is #!/usr/sww/bin/perl)

4a. Run 'siteplan'.

   Here's a sample session:

   % siteplan

   Welcome to the Mariposa Site Planner.
   This script will help you create your
   Mariposa installation.

   Select the hosts on which Mariposa
   will run.  We'll prompt you with the Mariposa
   host identifier -- please enter a host name,
   followed by _RETURN_.  When you are finished
   entering names, just hit _RETURN_ at the
   prompt.
   host #1: gaia
   host #2: faerie
   host #3: eden
   host #4: uptopia
   mp_hostaddr: Cannot get host entry for host "uptopia"
   Sorry, that's an invalid hostname. Please try again.
   host #4: utopia
   host #5: 


   Here is the host info:
   hostid: 1 -> gaia (address: 522526848)
   hostid: 2 -> faerie (address: 891625600)
   hostid: 3 -> eden (address: 941957248)
   hostid: 4 -> utopia (address: 908402816)
   Do you wish to change any information? [n]n
   Writing the SQL file...done.
   Writing the bootstrap program...done.

   This deposits two additional files, "mpbootstrap.pl" and
   "initsite.sql" into the bin directory.

4b. Copy the executables and template database to another machine.

   Go up one directory level.

   % cd ..

   Pack up the bin and data directories:

   % tar cvf remote.tar bin data

   Put the tarfile on the remote hosts:

   % ftp faerie
   (details omitted)

   On the remote system, unpack the tarfile.

   faerie% tar xvf remote.tar

   (Be sure to copy and unpack the tarfile on each remote host.)

4c. Run 'siteinstall'.

    Make sure that your PATH includes the bin directory; if you've
    installed the executable in someplace other than where it
    was installed on the build machine, be sure to set PGDATA
    before you run any executables.

    (For example, if on the remote host 'faerie' you install the
    system in /export/home/mariposa, make sure that your PATH
    includes /export/home/mariposa/bin and that PGDATA is set
	to /export/home/mariposa/data.)

	% siteinstall
    Determining site id based on your siteplan...
    Running initdb with hostid set to 2...
    (This should take a couple of minutes.)
    initdb: hostid=2
    sourcing initsite.sql
    %

    Make sure you repeat this step for each host in your siteplan.


5. Start the sitemanager at each site.

   Now, you are ready to make the system operational by running the
   sitemanager daemon. There are a few environment variables which affect
   its operation:
	PGDATA	- location of the database (e.g. /export/home/mariposa/data)
	PGPORT	- TCP port where it listens for connection (e.g. 4321)
   You don't have to set these variables if you use the (compile time) 
   default.  (You do have to set PGDATA if you're installing a remote
   system in a different filesystem location.)

     % sitemanager -S

6. Other configurations.

   For a single-site system, just run initdb:

   % initdb

   Then start the sitemanager as with Step 5, above.

   For a "distributed" site run on a single machine, run the
   initmp script located in the bin directory:

   % initmp

   This will create a number of data directories and databases
   for you; you will need to set PGDATA and PGPORT for each
   sitemanager you run.  See the 'dist' test in $(srcdir)/test/dist
   for more information about this configuration.
   
6. Testing.

   We suggest you run the regression tests to make sure the release
   was installed successfully. The regression tests can be found in
   src/test/regress. 

     % cd /private/mariposa/src/test/regress
     % gmake all runtest

   This will run a whole slew of regression tests and might take a long
   time to run.  When it's done, the output is in the file obj/regress.out.
   You can compare this to a sample run that we supply in the file 
   sample.regress.out. (You should get roughly the same output except
   for some pathnames.) 

     % diff obj/regress.out sample.regress.out

   The regression test takes about half an hour to run on a DEC Alpha 3000.

7. Run queries.

   After the database is initialized, you can create a new database. To
   create a database, do the following:

     % createdb foo

   To connect to the postmaster, you have a choice of two front-end programs.
   ("psql" is recommended.  "monitor" is the old terminal monitor
     supplied in earlier versions of Postgres)
   
     % psql foo
    Welcome to the Mariposa interactive sql monitor:
      Please read the file COPYRIGHT for copyright terms of Mariposa
        
       type \? for help on slash commands
       type \q to quit
       type \g or terminate with semicolon to execute query
     You are currently connected to the database: foo

    foo=> 

----------------------------------------------------------------------
Questions? Bugs? Feedback?

Check out our WWW site at:

	http://epoch.cs.berkeley.edu:8000/mariposa/

There, you will find late-breaking news, updates, bug lists,
and contact information.

Or, send email to:

	mp-questions@postgres.berkeley.edu

----------------------------------------------------------------------