Installation Information

Drafted: 2002.02.16 11:43pm

Aaron

Important Note

This version of the Database Browser (0.4) is deprecated. A new version is under development. It would probably be a better idea to hold off on downloading this software until which time as Dbb 0.5 is ready to go.

Forward

This document covers the process of installing and configuring Dbb onto a linux box for use with an Apache server. The concepts introduced here can be easily applied to help install Dbb on other systems as well.

Important note on Security

It is important to note that Dbb is not instantly or inheritly secure. It has been designed to work securely in an https environment by not sending information back to the client web browser via the URL or within cookies. It also stores no persistent data which may reveal user / password information. Transmission of administrative SQL passwords across an insecure page is a terrible and dangerous idea. For more information on adding security to your Apache web server, see http://www.modssl.org.

Installation Types

Dbb is quite flexable and so it may be installed in many different configurations quite easily. Of the many, many permutations of installation layouts Dbb is capible of, this document will describe the two most common.

Root VirtualServer Installation

Creating a virtualserver exclusively for Dbb is quite easy to install and configure as well as secure. This requires you have access to the configuration of the webserver you wish to use which almost certainly requires root privileges on the server hosting your site. If you do not have these privileges, or don't understand what this means, this install type is not for you. This install requires you already know how to configure an apache virtualserver and have a decent understanding of *nix commands.

Step by Step

1. Get the Root VirtualServer installation package of dbb from the download page here.
2. Create a subdirectory wherever is appropriate for hosting web pages on your server. Often this is located in '/home/httpd/' or '/var/www/'. Be careful that the directory you are creating is not already addressed by a previously configured virtualserver.
3. Copy the Root VirtualServer dbb package into the newly created directory and extract the files within the archive. This should create a layout similar to the following:

   0001 ./dbb-0.4.x/ 0002 ./dbb-0.4   ->    dbb-0.4.x/ 0003 ./dbb-html-0.4.x/ 0004 ./html   ->    dbb-html-0.4.x/ 0005

4. Configure a new virtualserver within apache with the document root specified as: <path/to/dbb/install>/html/
5. Now would be a great time to configure the security of your new virtualserver. Remember, clear text passwords bad.
6. Read the "Special Requirements & Filesystem Permissions" Section
7. After restarting your apache server, surf to the new virtualserver in your favorite browser and voila!

Inline Installation

For those of use without access to the configuration files used by our webserver, Dbb must be installed in a subdirectory of an existing site. It is important to note that there are security issues associated with this installation type that should be considered. See "Known Security Issues" below. If you don't have access to the configuration of your web server you might be in for a nasty adventure trying to emulate some of the required characteristics of Dbb. I feel for you, but there's not much that can be done from here.

Step by Step

1. Get the Inline VirtualServer installation package of dbb from the download page here.
2. Create a subdirectory called 'dbb' inside your web root directory (where your html files are) where you want dbb to be.
3. Copy the Inline VirtualServer installation package to this newly created directory.
4. Extract the contents of the archive, usually "gunzip -c packageFileName.tar.gz | tar -x" will do the trick.
5. Read the "Special Requirements & Filesystem Permissions Section"
6. Surf to your site and go to directory you chose to install dbb in. Enjoy.

Special Requirements & Filesystem Permissions

Dbb requires certain features of your webserver be configured in certain ways. If you do not have access to these configurations, many may can be emulated by dbb. Many (or all) of these special requirements will be resolved to make Dbb as portable as possible. If you have no idea what this section is talking about or are unable to fix these problems for whatever reason, keep checking back to this site for updates on when these requirements are removed.

Requirements

1. The directory 'dbb-0.4.x/tmp' must have write permissions by whatever user your web server executes as. This will not be a requirement in future versions of Dbb.
2. PHP's magic quotes must be shut off! This will not be a requirement in future versions of Dbb.
3. Apache must parse html files for PHP. This will not be a requirement in future versions of Dbb.

Summary

This document is incomplete. It is here as a basic framework to allow experienced administrators to install and configure Dbb. Future versions of dbb will be more friendly to new users. Keep checking back if this document makes/made no sense to you.