view release on metacpan or  search on metacpan

docs/ACEDB.HOWTO  view on Meta::CPAN

			ACEDB HOWTO

ACeDB is poorly documented and very intimidating to the new user.
Despite this, it is not hard to install the database and get it
running.

OBTAINING THE SOFTWARE

ACeDB is available in both binary and source code form.  I strongly
recommend that you install the server from source code. The source
distributions tend to be more up to date than the binary
distributions, and subtle differences between shared libraries can
cause ACeDB binaries linked on one platform to behave differently on
another.

ACeDB distributions are available at:

  ftp://ftp.wormbase.org/pub/wormbase/software/
  ftp://ncbi.nlm.nih.gov/repository/acedb/

I recommend that you use the ftp.wormbase.org URL, as this contains
the latest stable snapshot of ACeDB that I use for testing and
debugging the current release of AcePerl.

COMPILING THE SOFTWARE

Unpack the software into its own directory:

	1) mkdir acedb
	2) gunzip -c acedb-latest.tar.gz | tar xvf -

Compile the software.  The makefile requires that an environment
variable named ACEDB_MACHINE be defined.  This environment variable is
in turn used to select the makefile to be used to compile.  To figure
out what to set this environment variable to, type "make". You will
receive an error message listing the alternatives. Choose one for your 
system, and run "make again".

	3) cd acedb
	4) make  (error message listing possibilities)
	5) setenv ACEDB_MACHINE LINUX_4  (for example)
	6) make

This will create a subdirectory named bin.LINUX_4 (or whatever your
operating system is), containing the executables along with a number
of other files.

INSTALLING THE SOFTWARE

ACeDB runs as an Internet server.  As such, it should not be run as
root, but as an unprivileged user.  My strategy has been to create a
new user and group, both named "acedb".  The server runs as "acedb",
and all database developers belong to the "acedb" group, giving them
write access to the database files.

After creating the acedb user, create a "bin" directory and copy the
executables into it:

	1) cd ~acedb
	2) mkdir bin
	3) cd ~/acedb (where the source code was compiled)
	4) cd bin.LINUX_4 (or whatever)
	5) cp xace tace giface saceserver sgifaceserver makeUserPasswd ~acedb/bin/

Now put ~acedb/bin on your path so that the Ace::Local module can find
the giface and tace programs.  This usually involves editing .cshrc or
.bashrc to change the PATH variable.  (See your system administrator
if you don't know how to do this).

CREATING DATABASES

Each ACeDB database lives in a separate subdirectory, which I
conventionally place under ~acedb/.  You will often be installing a
compressed database archive, such as the C. elegans database (see the
NCBI FTP site).  In this case, simply unpack the database into the
~acedb/ directory.  Programs like xace, tace, and the servers will
refer to the database by its path. Within the database directory
should be the subdirectories databases/, wspec/, wdoc/, wgf/, wquery/,
and possibly others.  If not, make sure that you unpacked the database
package correctly.

Now examine and edit the file ~acedb/wspec/passwd.wrm.  This contains
the names of user accounts that are allowed to write to the database.
Make this file readable by everyone, but only writable by you (and
other trusted users).  If you will be running an ACeDB server, you
should examine the file ~acedb/wspec/server.wrm.  This contains read
and write policies for the server.  You can restrict who can read and
write to the database, although currently you are limited to
restricting read and write privileges to local users versus non-local
users.

Creating a new database from scratch is somewhat more difficult,
because you have to create an appropriate models (schema) file.
Please see NEW_DB.HOWTO for help.