The FreeBSD Diary

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.

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.

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.

1. Extract the code to another location:
   $ mkdir ~/tmp/
$ cd ~/tmp
$ tar xvzf ~/phorum-3.3.2c.tar.gz

2. 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.

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.

1. Create the database. This assumes you have permission to do this. If not, you may have to su to pgsql.
   $ createdb fsphorum
CREATE DATABASE
2. 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=#


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.

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 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 should now be up and running. Go for it.

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.

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.

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

cvsup ~/freshsource-supfile

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.