$Id: INSTALL.txt,v 1.5 2003/05/23 17:00:15 csnyder Exp $

How to INSTALL berylium

Berylium is a collaborative content-management system built to run in an
Apache/MySQL/PHP (AMP) evironment. It is a set of PHP classes and functions,
bundled with a set of interface templates, that allow users to create and manage 
sites, folders, documents, images, and other objects via a their web browser.

Ideally there is one berylium install per physical server, shared by all
berylium sites on that server.

Berylium is also well suited for content management at the workstation level,
email me for more information about this (chris@psydeshow.org).


REQUIREMENTS:

You will need to have installed and configured Imagemagick, MySQL, Apache
(mod_php and mod_ssl), and PHP. If you are lucky enough to be starting from
scratch, have a look at the Asparagus Server Specification. See
http://chxo.com/asparagus for more information.

You will need to be (or be in contact with) the server's system administrator in
order to set up berylium from scratch. Note to sysadmins, it is easy to use a
single berylium implementation with many virtual hosts. See ADDING ADDITIONAL
SITES below.


UNPACKING THE SOURCE:

This document assumes that you have unpacked the source code into your home
directory (/home/yourname), using something like:

	/home/yourname $ tar xzvf berylium-2002-06-28.tar.gz

This will create the following tree:

	/berylium		: berylium root
	/berylium/http	: things that go in your http, secure-http, and/or public_html folder
	/berylium/http/bicons	: (hopefully) GPL'd icons
	/berylium/code	: the bulk of the server code
	/berylium/code/contexts	: the standard context files 
		(these determine the interface)
	/berylium/code/policies	: the standard policy files 
		(these determine levels of access)
	/berylium/doc	: documentation and notes

Replace username with your username and nobody with the groupname the webserver
uses. This will set the proper permissions on the existing files and create a
web-writeable directory called files where the server will store uploaded and
cached files.

chown -R berylium.nobody berylium
chmod -R 750 berylium
mkdir berylium/files
chown -R berylium.nobody berylium/files
chmod -R 770 berylium/files

Copy the icons, configuration, and two setup scripts to your webserver document
root (usually /home/username/http or /home/username/public_html but could be
/usr/local/apache/htdocs).

cp -rpv berylium/http/bicons /home/berylium/http/
cp -pv berylium/http/beryliu* /home/berylium/http/
cp -pv berylium/http/config.dist /home/berylium/http/config
cp -pv berylium/http/test.php /home/berylium/http/

Edit http/config, changing /home/username/berylium to /home/yourname/berylium
(the location of the berylium root).

Then set-up your secure-http directory if it's different from the regular http
directory (I recommend not if possible...):

cp -pv berylium/http/beryliu* /home/berylium/secure-http/
cp -pv berylium/http/test.php /home/berylium/secure-http/
cp -rpv berylium/http/bicons /home/berylium/secure-http/
cp -pv /home/berylium/http/config /home/berylium/secure-http/config

Copy berylium.conf.dist to berylium.conf.

cp -pv berylium/code/berylium.conf.dist berylium/code/berylium.conf



HTTPD SETUP:

Add the following to your /usr/local/apache/httpd.conf. It forces apache to
treat http://yoursite.org/berylium as a php script no matter what comes after it
in the HTTP_REQUEST from a client. Either add this in a VirtualHost container,
or in the main Server Config depending on whether you want it to apply to all
sites on your server. Note that this will not work from an .htaccess file.

	##
	## Berylium Script Forcing
	##
	<Location /berylium >
	    ForceType application/x-httpd-php
	</Location>

Make sure you can see both http://yoursite.org/test.php and
https://yoursite.org/test.php and that http://yoursite.org/berylium/test shows a
database connection error (and not something like "Failed opening xxx for
inclusion" which means that there are file permissions errors).



DATABASE SETUP:

Log in to mysql as the root user: /usr/local/mysql/bin/mysql -u root -p
Input the following SQL (cut-n-paste is fine but change the passphrases
first!!!) The administrative passphrase is what you might use from a command
line to access the database using '/usr/local/mysql/bin/mysql -u berylium -p
beryliumdb', and beryliumweb's passphrase is what the webserver will use to
access the database as beryliumweb, a user without the ability to delete
anything.

CREATE DATABASE beryliumdb;
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON
beryliumdb.* TO berylium@localhost IDENTIFIED BY 'administrative passphrase' ;
GRANT SELECT, INSERT, UPDATE ON beryliumdb.* TO beryliumweb@localhost
IDENTIFIED BY 'beryliumweb's passphrase' ;
FLUSH PRIVILEGES;



CONFIGURING BERYLIUM:

Edit berylium/code/berylium.conf:

The $wordkey is a special phrase that will be used to encrypt all the passwords
in your database-- change the initial value, write it down somewhere safe and
NEVER CHANGE IT AGAIN -- if you change it after members are added to the
database you will SCRAMBLE all of their passwords. This is not
industrial-strength security but at least if your database is compromised there
will be an additional decryption step required before your passwords can be
discovered. Write this phrase down and keep it in a file somewhere (unless
you're super-paranoid, then just remember it or something).

$dbuser and $dbpassword refer to beryliumserver and the webserver passphrase you
gave MySQL when you created the database above.

$adminemail is your email address in case something goes wrong.

Check your configuration at http://berylium.org/berylium/test again-- this time,
the only error should be something about your site not existing.



CREATING THE FIRST SITE:

Go to https://yoursite.org/berylium-init.php and fill out the form to create the 

initial site at yoursite.org, then click Submit. The next screen should tell you 

that all the tables and initial objects were inserted correctly. There should 
also be three updates that you will need to log into the database a perform by 
hand (it is okay to cut and paste).
