Installing YAZD

Introduction

Yazd is a web based discussion forums site.

Yazd is implemented in Java, with a database as its backend. It must be hosted within an application server.

It is an open source project, operating under the Apache licence.

Assumptions

This guide assumes the following software will be used:

All of these apart from Windows 2000 are freely available. It is entirely possible to run all of this software on the free Linux OS instead, but the installation process is slightly more complex. A HOWTO for Linux will be produced at some future point if there is sufficient demand.

We recommend that you update Windows 2000 to the latest Service Pack level before proceeding with this installation. Service Packs can be obtained from the Microsoft Windows Update web page: http://windowsupdate.microsoft.com/

Some or all of this software may function on other versions of Windows, but this document does not currently cover those scenarios.

Preparation

Download the following files and place them in a suitable directory. For the purpose of this document, we will assume you have placed them in C:\YAZD_INSTALL\

Installing the Sun SDK

Run C:\YAZD_INSTALL\j2sdk-1_4_2_03-windows-i586-p.exe

Accept the licence agreement

Do not customise the setup -- just click Next

The next screen will allow you to select the browser(s) into which you want the Java plugin installed. Your choices here will have no direct effect on the installation. Select Install once you have made your selection.

The SDK will be installed:

The SDK has now been installed:

Select Finish.

By default the Java SDK will have been installed to C:\j2sdk1.4.2_03\

Our assumption throughout the remainder of this installation will be that this is the case, so it would be best to check before continuing.

Installing Tomcat

Run C:\YAZD_INSTALL\jakarta-tomcat-5.0.19.exe

Click Next

Accept the licence:

Accept the default options. Click Next:

Remove the default path and replace it with C:\Tomcat5

This is to prevent problems where some applications have problems with the spaces in the pathname.

Click Next.

Now you have the option to change the port under which Tomcat runs on your machine. We will leave it as 8080, but this will require you to explicitly provide the port number. For example: http://fatmoggy.com:8080/ instead of http://fatmoggy.com/

If you prefer the latter behaviour then you can change the port number to 80, but this will cause problems if any other webserver is running (IIS or Apache, for example). The rest of the installation instructions assume that port 8080 is used -- it is possible to change this later, so if you’re in any doubt, leave things as they are.

You should also choose an administrator password. For the sake of clarity in this document we will use "unwise" as the administrator password. Do not use the same password or your machine will become vulnerable to attack. Enter this and select Next.

Enter the path to the SDK installed in the section "Installing the Sun SDK". You should not need to change the path given unless you have previously installed some other version of the SDK. Select Install.

The installation will proceed. On completion you will be presented with the following dialog. Deselect the "run Apache Tomcat" checkbox, then click "Finish"

You will be left with the RELEASE-NOTES file open in Notepad, which you may read and close.

Select the "Start Tomcat" menu option (StartMenu, Programs, Apache Tomcat 5.0, Start Tomcat):

The following Logo will be displayed briefly as the webserver starts.

Open a Web browser on the same machine and open the link http://localhost:8080/

You should see the following page. If you do, Tomcat is installed correctly.

Close the browser. At this point, you might like to take a tea break and try out some alternative browsers which are freely available. We like the FireFox browser from the Mozilla organization:

It stops popup windows, and allows you to do Tabbed browsing (we promise you’ll like it when you find out what it is).

Installing MySQL

Start Command Prompt (Start, Run, enter Cmd in the box):

At the c:\> prompt, type

cd C:\YAZD_INSTALL

At the C:\YAZD_INSTALL\> prompt, type

mkdir MySQL

At the C:\YAZD_INSTALL\> prompt, type

cd MySQL

At the C:\YAZD_INSTALL\MySQL\> prompt, type

c:\j2sdk1.4.2_03\bin\jar -xf ..\mysql-4.0.18-win.zip

This will "unzip" the compressed archive containing the MySQL installer. If you have WinZip or a similar program installed already, you may find it easier to use that.

Run C:\YAZD_INSTALL\MySQL\SETUP.EXE

Select Next:

Read the text panel. We will be using the default C:\MYSQL\ directory. Select Next:

Select Next:

Leave the default setting of "Typical" and select Next:

The installation will proceed and complete with the following dialog. Select Finish:

MySQL is now installed, but not configured and not running.

MySQL provides extensive documentation on their website: http://www.mysql.com/documentation/mysql/bychapter/index.html

The following should be enough to get you started with Yazd, however.

At your open command prompt, type:

C:\MYSQL\bin\mysqld --install

You should see the message:

Service successfully installed.

At the same prompt, type

NET START MYSQL

You should see the following pair of messages:

The MySQL service is starting.
The MySQL service was started successfully.

If you now load Services (Start Menu, Settings, Control Panel, Administrative Tools, Services)

You should find the following highlighted entry in the list:

The MySQL server may subsequently be controlled from the services control panel tool, and will automatically start when your machine starts.

Leave the command prompt open for use in the next section.

Installing Yazd

At the command prompt type:

cd c:\

At the C:\> prompt type:

c:\j2sdk1.4.2_03\bin\jar -xf c:\YAZD_INSTALL\yazd.zip

This will unpack the YAZD forum software to C:\YAZD\

At the C:\> prompt type:

cd yazd

At the C:\YAZD\> prompt type:

dir

You should see roughly the following:

At the C:\yazd> prompt, type:

mkdir data

Then type

mkdir logs

These will be used later to hold respectively forum data files and error logs.

Leave the command prompt open for the next section.

Configuring Yazd

Configuring the database

At the C:\yazd\> prompt, type:

cd database

You should now select a suitable name for your database within the database server. A note on terminology is called for here:

The "MySQL" application, though commonly referred to as a "database" is in full a "Relational Database Management System". That is to say, it manages databases. Each database is a repository of information, usually as the back end of a specific application.

So while for now you only want one "database" for your application, you may at some future point want a dozen different ones for a dozen different projects. So you require a name to allow you to distinguish them from each other.

Rather predictably we’re going to select "YAZD" as the name of our database, but if you think you might want to run several different discussion forums on the same machine (this is really out of the scope of this document) then you might want to give them different names.v

At the C:\yazd\database\> prompt, type:

C:\mysql\bin\mysqladmin create YAZD

At the C:\yazd\database\> prompt type

c:\mysql\bin\mysql YAZD < Yazd_mysql.sql

This will run the script "Yazd_mysql.sql" using the mysql command line tool on the database called YAZD, creating all the tables that are necessary for the forums to store their information.

Leave the command prompt open for the next section.

Securing the database

The MySQL database is not, by default, secure. The database is accessible over the network, and the password for the default (root) user has not been set.

This means that anyone can connect over the network to your machine and carry out arbitrary commands. Not good.

Genuinely "securing" a database like MySQL is well outside the scope of this document. Reading up on it would be a good step, particularly if you intend your forum software to be made available on the "public" internet.

For the purposes of this demonstration, however, we will simply assign a password to the "root" user, and create a specialised user for the forum software.

To set the root user’s password, which again we’ll set to "unwise" as a reminder that you should choose your own password here:

At the c:\yazd\database\> prompt type

c:\mysql\bin\mysql -u root

You should see the following prompt:

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 6 to server version: 4.0.18-max-debug

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql>

At the mysql> prompt type

SET PASSWORD FOR root@localhost=PASSWORD('unwise');

You should see the following prompt:

Query OK, 0 rows affected (0.03 sec)

mysql>

At the mysql> prompt now type

SELECT host,user,password from mysql.user;

The following table will be displayed:

+-----------+------+------------------+
| host      | user | password         |
+-----------+------+------------------+
| localhost | root | 496028d157c3cb33 |
| %         | root |                  |
| localhost |      |                  |
| %         |      |                  |
+-----------+------+------------------+
4 rows in set (0.00 sec)

Note that the user root on host localhost is permitted to login with a password (which has been recorded in an encrypted manner). The other three users have no passwords set, so their details must be deleted:

At the mysql> prompt now type:

DELETE FROM mysql.user WHERE PASSWORD='';

At the mysql> prompt now type:

FLUSH PRIVILEGES;

Now the only permitted user is root via a network connection.

We will now add a user who is permitted to access the YAZD database. We’ll call this user ‘yazd’ since it will act on behalf of the yazd software when accessing the yazd database, and we will again give it the ‘unwise’ password to highlight the fact that you should choose your own more suitable password here.

The yazd user is only permitted to access the database from the local machine, logging in with a specified password.

At the mysql> prompt type:

GRANT ALL PRIVILEGES ON YAZD.* TO 'yazd'@'localhost' IDENTIFIED BY 'unwise';

At the mysql> prompt type:

FLUSH PRIVILEGES;

At the mysql> prompt type:

exit

You should be back at the C:\yazd\database> prompt. The database is now more secure. However, we should stress it is only MORE secure, not SECURE. Various techniques could still be used to "crack" your database’s security and we strongly advise reading up on appropriate security techniques before deploying a live system.

Leave the command prompt open for the next section.

Preparing the Web Application

At the prompt type:

cd c:\yazd

At the c:\yazd\> prompt type:

ren application WEB-INF

At the c:\yazd\> prompt type:

notepad WEB-INF\classes\yazd.properties

The last line of the file currently reads:

path=

You need to alter this to read:

path=C:\\yazd\\WEB-INF\\classes\\yazd.properties

Save the file.

At the c:\yazd\> prompt type:

cd C:\YAZD_INSTALL

At the C:\YAZD_INSTALL\> prompt type:

jar -xf mysql-connector-java-3.0.11-stable.zip

At the C:\YAZD_INSTALL\> prompt type:

cd mysql-connector-java-3.0.11-stable

At the C:\YAZD_INSTALL\ mysql-connector-java-3.0.11-stable\> prompt type:

copy mysql-connector-java-3.0.11-stable-bin.jar c:\yazd\WEB-INF\lib

This copies the JDBC driver for MySQL into the Yazd application’s libraries directory so that it can be used to access the database.

Leave the command prompt open for the next section:

Selecting the "Skin"

Yazd permits you one of several "skins". Select the one you want, then copy the contents of the appropriate "skins" directory into C:\yazd\

For example, for the "vodka" skin, at the command prompt type:

cd c:\yazd\skins\

xcopy /s vodka\* c:\yazd

Try this first, then try some of the others once you’re a little more confident about the installation process.

You also need to move the "admin" skin into place:

mkdir c:\yazd\admin

cd c:\yazd\skins\

xcopy /s admin c:\yazd\admin

Configuring Tomcat

Open the following URL in your web browser:

Login as admin with the password you set in section XXX.

In the left hand "tree" view, expand Service (Catalina), then Host (localhost). Select Host (localhost).

The browser should look like this:

From the right hand panel, in the "Host Actions" pulldown, select Create New Context

Make the following changes in the resulting form:

Leave all the other settings as they are. Select the Save button.

The page should now say "Save successful!". Click "Commit Changes", then click "Logout".

Online Configuration of Yazd

Now you’re ready to carry out the rest of the configuration of Yazd.

Load the following URL:

You should see the following page:

Select "Continue".

On the next page, fillin the following fields:

(Our usual caveats about passwords apply). Once you’ve filled the fields, click Make Connection and you should see the following page:

At this point, you can breathe a huge sigh of relief, as all of the really tricky steps have been completed. Click Continue.

On this next page, provide the path C:\yazd\data\ in which to store data files. Click continue.

Now enter your personal details, or the details of the person who will be administering the forums:

For the password here, you should again select something appropriate. Select "Create Administrator" and you should see the following page:

Click the "Login to Yazd Admin" button and you should see the final page:

You’ve completed the installation process. You can now log in using your administrator account (created above) and create forums for your users.

Just to prove the point, if you now point your browser at the main page:

You should see the following empty forum page:

Administering Yazd

Yazd is a pretty dynamic system. You’re supposed to be able to create virtually unlimited forums, threads, users and so forth. This section of the HowTo will just walk you through creation of a very simple "Humour" forum.

Creating a user

Load the page http://localhost:8080/yazd/admin/ in your browser and login with the Administrator account.

This brings you to the Admin page.

Click the "Create User" link in the "Add new user permission" box.

Fill in the fields for an appropriate user:

Note that I’ve selected the "use email" button. It’s generally a good idea to do this, since email addresses have two very useful attributes:

• Users can generally remember them
• They’re unique to that user

Click Create User. (You may see an error as the username is filled in for you -- if so, just fill in the password fields and click Create User again).

Your user has been created.

Creating a Forum

Select Forum Settings from the tabs at the top of the page.

Select Create from the menu on the left. This brings you to a page in which you can describe your forum:

Provide a short forum name and a long forum description in the appropriate boxes:

Select Create.

You have created your forum, but by default nobody but you can use it.

Scroll down to "Add New User Permission"

Select the appropriate items in the lists so that it reads:

I want *Anonymous Users to be able to read content of this forum.

Click the "Add User Permission" button

If you scroll to the top of the page, you should see that the first list has now altered to the following:

So far anyone can read topics, but nobody can post topics.

We’ll let any user post a reply to an existing topic, so in "Add new user permission" select the options to allow "Anonymous Users" to be able to "post messages in" the forum:

Select Add User Permission.

Only a selected user is going to be able to create new "threads" (topics) for discussion. We’ve already created the user. We’ll actually allow him additional powers:

He can "read content" and "post messages in" threads, but he can also create new threads (topics) in the forum. Finally, he’s the "forum moderator", which means that he has the power to delete inappropriate threads from other users and otherwise look after the content of the forum. Select "Add User Permission". The top of the page should now list the following user permissions:

That seems like enough to be going on with.

Lets take a look at our handiwork from the point of view of the users:

Logout, and then load http://localhost:8080/yazd/

The topic has been created. Login as the "moderator" account:

Go to the following URL: http://localhost:8080/yazd/ ( a link is missing here -- when you start to modify your own skins for the application, you will want to add this) and hit reload.

Select the forum name:

And click the "post new message" button:

Hit "Post Message" and your topic has been added to the forum.

Click around for a bit now. Experiment with some of the other administrative features of Yazd. Try out the filter features. Try using the forums as different users.

Once you’re up to speed, you will want to look at the JSP pages.

Tidying up

You will probably want to archive the contents of the YAZD_INSTALL directory for future use, but they are not required for operation of the system.

You may want to alter the service settings of Tomcat to ensure that it starts automatically (on boot). To do this, load Services from Control Panel, Administrative Tools

Select "Automatic" for the startup type, then select "Apply". You will not need to "start" the service as it is already running.

Bugs

I encountered two irritating bugs in yazd while writing this document.

• As noted above, the login page does not have a link to take you back to the forums once you’ve logged in. Several other pages suffer from this sort of problem, though generally in a more recoverable way.
• If you stop the process of "forum creation" before you have committed to creating it -- say to create a new user -- you will be unable to change any aspect of the forum, yet it will be listed on the forums page of the main site. This may be specific to the configuration described here.

Conclusions

Yazd forums are quite complex to install, but once up and running they’re very easy to administer.

Given some of the bugs, the forums are probably not quite "ready for prime time", but they’re pretty close.