Installing and configuring Phorum using cvs

This is the first of two articles about importing a third party product into cvs and using for different projects in different
ways. The steps I outline below may not be the best way of doing things, but I’m about to find out.

The prerequisites for this article are:

experience with cvs
knowledge of cvsup
familiar with cvsup server

My current project is FreshSource. I also have other projects such
as this website and FreshPorts. All of these websites use a web-based
message board called Phorum. It is a very flexible and easily configured
product. I’ve been using it for years.

I use cvs for publishing my website. For example, this article I’m typing now is first
saved to a file. That fie is then added to the cvs repository. When I’m ready to put the article onto the
website, I will use cvsup to get the file from the cvs repository onto the
web server.

The problem I’m trying to solve here is the use of Phorum on three different website, but maintaining only
one instance of Phorum in the cvs repository. If a new version of Phorum arrives, I don’t want to manually
upgrade three websites. I want to upgrade once and only once.

Hopefully this strategy will work and it will be flexible and simple.

Structure of my websites

My websites follow the same structure. Each website resides within their own directory under
/web/. The directories under /web/ have the same name as the domain name. For example, freshports.org
exists under /web/freshports.org/. Within each website directory, I will have a www directory, which contains
the HTML for the website. I have other directories for configuration items etc. These structures will become
obvious in the first stage: installation and configuration.

Initial Phorum Installation/Configuration

Here are the steps. For mor detail on Phorum configuration please refer to the docs
directory after you extract the source code from the Phorum tarball.

The following steps will fetch the tarball, extract the files, and move into the directory.

cd /web/example.org fetch http://phorum.sourceforge.net/downloads/phorum-3.3.2c.tar.gz tar xvzf phorum-3.3.2c.tar.gz cd phorum-3.3.2c

Notice that I put phorum one directory up from the www directory, where my HTML code usually appears.
I will now create a link so that the URL will work:

cd cd /web/example.org/www ln -s ../phorum-3.3.2c phorum

Remember to read docs/install.txt. It is your friend.

The following is the output produced when running the security script provided by Phorum.
My responses are shown in bold.

$ bash scripts/secure
This script will help you secure your Phorum. Please answer the following questions. Renaming the admin directory is also a simple way to keep out intruders. New admin directory name [admin]: MySecretDirectory It is a good idea to move the settings dir out of the web tree. You may enter any path you like below. Phorum settings path [MySecretDirectory/settings]: /web/example.org/MySecretDirectory/settings .htaccess security works only with apache and may cause internal server error if the server doesn't allow you to change AuthConfig settings If you get internal server error, ask your administrator to "AllowOveride AuthConfig" for the directory your phorum installation is in. Do you want .htaccess security [n]? y The next questions have to do with file permissions for the web server. If you are unsure of the answer, answer no. Does this web server run as user dan [n]?n Does this web server run as group dan [n]?n Securing Phorum.... Moving the admin dir... mkdir -p /web/example.org/MySecretDirectory/settings Moving the settings dir... Updating common.php... Setting file permissions... Securing directories...
******************************************************************** * * * You still need to use the admin script to configure a few items. * * Point your web browser to the admin script and it will tell you * * what to do. * * * * After that please refer to the readme.txt for instructions on * * adding forums and folders. * * * ********************************************************************

It is important to note that I just created a new directory:
/web/example.org/MySecretDirectory/. When importing into CVS, we’ll have to remember
to include those files.

I then wanted to compare the original code and the changes performed by the above step.
First, I again extracted the code to a new location, then ran diff.

Extract the code to another location:
$ mkdir ~/tmp/ $ cd ~/tmp $ tar xvzf ~/phorum-3.3.2c.tar.gz
Run the diff:
$ diff -r phorum-3.3.2c ~/phorum-3.3.2c Only in /home/dan/phorum-3.3.2c: admin diff -r phorum-3.3.2c/common.php /home/dan/phorum-3.3.2c/common.php 8c8 < $settings_dir="/web/example.org/MySecretDirectory/settings"; // no ending slash --- > $settings_dir="./admin/settings"; // no ending slash Only in phorum-3.3.2c/db: .htaccess Only in phorum-3.3.2c/docs: .htaccess Only in phorum-3.3.2c/include: .htaccess Only in phorum-3.3.2c/lang: .htaccess Only in phorum-3.3.2c: MySecretDirectory Only in phorum-3.3.2c/plugin: .htaccess Only in phorum-3.3.2c/scripts: .htaccess $

As you can see, some new .htaccess entries have been created and a new directory
(MySecretDirectory. and the settings_dir value has
been changed accordingly.

Creating the Phorum database

I am using PostgreSQL as my database. Phorum can also use mySQL.
My instructions in this section are PostgreSQL-specific. The mySQL link above should show you how to perform the
mySQL equivalent.

Create the database. This assumes you have permission to do this. If not, you may have to su to
pgsql.
$ createdb fsphorum CREATE DATABASE
Create the user as which Phorum will connect
$ psql fsphorum Welcome to psql, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms \h for help with SQL commands \? for help on internal slash commands \g or terminate with semicolon to execute query \q to quit fsphorum=# create user MyPhorumUser with password 'MyPassword'; CREATE USER fsphorum=#

Final Configuration via your browser

Now that you have done the initial Phorum configuration and created the database, it is time for the
final configuration, which can be done via your web browser. If you were to browse to your phorum URL
now (e.g. http://www.example.org/phorum/, you would see the following message:

You need to go to the admin and fix your database settings.

This should be your clue to instead browse to your administration directory as specified in a previous section.
In my example above, this URL would be: http://www.example.org/phorum/MySecretDirectory.
At this location, you should see the following:

I selected “PostgreSQL 6.5 or newer” because I am using PostgreSQL 7.2 and clicked on Submit.

The next screen you will contains the settings which Phorum will use to connect to your database.
Use the settings you specified when creating the Phorum database. Note that because my database
server and my web server runs on the same computer, I did not specify a value for “Database – Server Name”.

You will now be prompted for the administration user details. This is the user who will be permitted to
modify the Phorum settings online. Any phorum user can optionally create a user profile for themselves.
This profile ensures a certain amount of security in that it implements some simple steps to prevent
people from impersonating others. You can use this administration user when you post message to the
phorum. You can fill in the details at a later stage.

The next step is the specification of the Phorum URL. The default value was correct for me, but you may
wish to alter it should your needs differ from mine. You must supply an email address.

That’s it. You’re all done. You should now click on the link provided and then login using the
administration details you supplied in a previous step.

Modifying your Administration User profile

Creating a new phorum is achieved via your browser. The URL will vary, but it should be something of the form
http://www.example.org/phorum/MySecretDirectory/. Under Forum Maintenance, click on UserAdmin.
Click on edit on the line containing your name.

Creating a new Phorum

Creating a new phorum is achieved via your browser. The URL will vary, but it should be something of the form
http://www.example.org/phorum/MySecretDirectory/. Under Forum Maintenance, click on New Forum.
For a simple phorum, the only fields I filled in were Name, Description and Table Name.

If you then click on Forum Index, you will be able to create the first post…. But you may wish to
create a user profile. I do this to ensure that nobody else can impersonate me within the phorum. NOTE
that you cannot use the same email address for your login as that which was specified for the

Phorum is now running

Phorum should now be up and running. Go for it.

Importing Phorum into cvs

In a previous article, I wrote very briefly about customizing the pages. In this
article, I hope to provide sufficient detail of my customization process so that you can customize your own.
You may not wish to import the phorum code into cvs. I am doing that only because I use Phorum on multiple
websites with each website having custom configuration.

You will create your own cvs repository if you don’t already have one. My repository
already exists. In this case, my CVSROOT was set to /home/repositories/3rdPartyProducts.
I actually want the Phorum code to reside within a subdirectory of that directory. I’ll show you how I did
that.

The key point to remember is we have Phorum spread across two directories (phorum and MySecretDirectory).
Both of these will need to be imported into cvs. Before you do this, remember to set CVSROOT accordingly.
See the cvs article mentioned in the previous paragraph for details. Here is how I did the import:

cd /web/example.org mkdir temp cp -rp phorum-3.3.2c temp cp -rp MySecretDirectory temp cd temp cvs import phorum stable Phorum_3_3_2c cd .. rm -rf temp

WARNING: I am writing the above long after I actually did it and my notes are incomplete. The above may not
be correct.

Then I moved away the original code and grabbed the copies from CVS:

cd /web/example.org mv phorum-3.3.2c phorum-3.3.2c.original mv MySecretDirectory MySecretDirectory.original cvs co -d phorum-3.3.2c phorum/phorum-3.3.2c cvs co -d phorumsecrets phorum/phorumsecrets

The -d options above ensure that the collections in question go into
the directory specified. For example, if I didn’t specify it for the first line, we would get
phorum/phorum-3.3.2c created instead of phorum-3.3.2c.

I now have copies of the original code in the same directories phorum-3.3.2c
and phorumsecrets.

Local customization

Each of my websites will have have their own customization. I will handle these customizations by creating
one branch for each website. Here is how I created the branch:

cd /web/example.org/MySecretDirectory cvs -q tag -b Branch_FreshSource cd ../phorum-3.3.2c cvs -q tag -b Branch_FreshSource

To be sure I have the correct revision and branches sitting around, I then removed the above directories,
and did another checkout:

cd /web/example.org rem -rf phorum-3.3.2c MySecretDirectory cvs co -d phorum-3.3.2c -r Branch_FreshSource phorum/phorum-3.3.2c cvs co -d phorumsecrets -r Branch_FreshSource phorum/phorumsecrets

Now I’m ready to start changing things which are relative to a particular branch.
These localizations are found in two places:

MySecretDirectory/settings: forums.php
phorum-3.3.2c/include: footer.php header.php

forums.php should not be modified by hand. This file is maintained by the
administration steps performed via your browser.

footer.php and header.php are pretty much constant.
I modified them to include my standard code.

After testing the changes, I checked them in.

Publishing the changes

This section assumes you are already running a cvsup server.

I handled this new collection by creating two new entries in the sup directory on the cvsup server:

phorum-3.3.2c – contains two files:
$ less list.cvs upgrade phorum-3.3.2c $ less releases cvs list=list.cvs prefix=/home/repositories/3rdPartyProducts/phorum
MySecretDirectory – contains two files:
$ less list.cvs upgrade MySecretDirectory $ less releases cvs list=list.cvs prefix=/home/repositories/3rdPartyProducts/phorum

On my web server, I had the following supfile:

$ less ~/freshsource-supfile *default host=localhost *default base=/usr/websites/freshsource.org *default release=cvs *default delete use-rel-suffix *default umask=007 *default preserve *default tag=. freshsource-www www freshsource-config
phorum-3.3.2c tag=Branch_FreshSource maestra0618 tag=Branch_FreshSource

To publish, I just issue this command:

cvsup ~/freshsource-supfile

What about other websites?

I have not tried any other website yet. Only FreshSource. My guess is that I will need to create a different
branch for each website.