User:Dan Nessett/Technical/How to set up a CZ clone on CentOS 5

These instructions describe how to set up a LAPP stack (Linux Apache2 Postgres PHP stack) on CentOS 5.4. They are intended as an alternative to the instructions for creating a LAPP stack on Ubuntu for the purpose of creating a local CZ clone. They have been tested and verified to work on a fresh CentOS 5.4 install.

It must be noted that unlike Ubuntu, CentOS is much more expert friendly and much less novice friendly. For those without significant experience with Linux systems (specifically, installing and administering them), the recommended OS for a CZ clone is Ubuntu. However, the production version of the CZ wiki runs on CentOS, so for those with the requisite experience and skills, implementing a CZ clone for development work on CentOS has certain advantages. But with those advantages comes risks. The yum software installation system on CentOS is prone to significant configuration problems, especially when setting up its repositories. So, those choosing to use CentOS do so at their own risk. Caveat Emptor.

Installing postgres

The version of postgres we want is not available through the normal CentOS software repositories. So, we have to modify the repository information to direct yum to install the correct version. (Note: these instructions are based on those given at Yet Another Guide.

First find out what is the latest install package for postgres 8.3 (install packages for CentOS have the suffix rpm). Using a new tab or browser window, follow the link postgres rpms. Three files should display in the browser window. One of these will have the name pgdg-centos-8.3-x.noarch.rpm, where x will be a number, such as 6. Now download the appropriate yum repository configuration by entering the following at a terminal command prompt (replacing the x in the file name with the integer just discovered):

cd /tmp
sudo wget http://yum.pgsqlrpms.org/reporpms/8.3/pgdg-centos-8.3-x.noarch.rpm

Then install this information using the following command (again changing the x to the appropriate integer):

sudo chmod +x pgdg-centos-8.3-x.noarch.rpm
sudo rpm -ivf pgdg-centos-8.3-x.noarch.rpm

If you are working on a CentOS installation on which some other software has already been installed, it is possible that other repositories are indicated in the yum configuration files that may interfere with the installation of postgres 8.3. You can determine this as folows. Execute the following commands:

cd /etc/yum.repos.d
sudo gedit CentOS-base.repo &

If this file is non-empty, then do the following. (If the file is empty, simply close it without making any changes). There are sections in the configuration file each headed by a word in square brackets. If there are two sections labeled [base] and [updates] then at the bottom of those sections add the line:

exclude=postgresql*

Click on the Save button at the top of the edit window and close it.

Now execute the following commands:

sudo yum install postgresql
sudo yum install postgresql-server

For each command a bunch of text is displayed followed by a line that specifies the total download size. The next line is a prompt: Is this ok [y/N]:. You must type y. The default is N, which (of course) means no and taking it will abort the install.

The install of postgres on CentOS does not initialize the directory that postgres uses to store database information. So, the next step is to do this. Execute the following commands:

sudo /etc/rc.d/init.d/postgresql initdb

Installing postgres doesn't mean the server starts up when the system boots. We have to configure the system to do that. First, check that chkconfig is in your execution path. At a command prompt enter:

chkconfig

If the error bash: chkconfig: command not found is returned, you will have to add /sbin to $PATH. This requires editing .bash_profile (remember to cd to your home directory):

gedit .bash_profile &

In the edit window there should be a line starting with $PATH. At the end of this line add :/sbin (don't forget the colon at the beginning of this text and there should be no space between the colon and the rest of the line). Then save the edit, exit the editor and type:

source .bash_profile
chkconfig

This should result in an error message about usage. When chkconfig is working, enter the following commands:

sudo chkconfig --add postgresql
sudo chkconfig postgresql on

Now reboot your system and when that completes open a terminal window. Type:

su
su postgres
psql

A welcome message should display, followed by hints on psql commands and then the prompt postgres=#. At this prompt type \q.

Your terminal identity was changed from your CentOS username to root and then to postgres. Get back to root by typing:

exit

You should see a # prompt. There is one more thing we have to do before proceeding. In CentOS, the default trust model is ident based. This causes problems when configuring the postgres databases using pgAdmin III. So, we need to make one change to the postgres configuration file. Execute the following commands at a terminal window prompt:

cd /var/lib/pgsql/data
gedit pg_hba.conf &

An edit window should appear. Scroll to the end of the file and find the entry with the comment "local" is for Unix domain socket connections only. The next entries control access when connections to the postgres server come from the local host. Copy the text below and replace the corresponding text. The entry should now look like the following:

# "local" is for Unix domain socket connections only
#local   all         all                               ident sameuser
local   all         all 				trust
# IPv4 local connections:
#host    all         all         127.0.0.1/32          ident sameuser
host    all         all         127.0.0.1/32          trust

Save the file and exit the editor. Now restart the postgres server with the following command:

/etc/rc.d/init.d/postgresql restart

This change allows you to manipulate postgres through pgAdmin III without changing your CentOS user identity using su or sudo. The install of postgres is now complete. You can exit from root or remain at root and ignore the sudo prefixes in the next section.

Installing apache2 and PHP

Installing postgres is a lot of work. Fortunately, installing the other two components of the LAPP stack takes much less effort. First, we will install the apache2 web server. In a terminal window execute the following command:

sudo yum install httpd

Follow the normal install procedure by answering y to the question. You may be prompted with a question whether it is OK to import a GPG key. If so, answer y.

After the install completes, execute the following two commands:

sudo chkconfig --levels 235 httpd on
sudo /etc/init.d/httpd start

Then in your favorite browser, create a new tab or window and in the URL field type: http://localhost. An apache2 test page should display. If so, apache2 is installed. If not, then make sure you correctly executed all of the commands specified above.

To install PHP5 is even simpler. Execute the following commands:

sudo yum install php
sudo yum install php-pgsql

If you want to test that PHP5 is working properly, execute:

cd /var/www/html
sudo gedit phpinfo.php &

When the empty edit window appears, enter the following information:

<?php
phpinfo();
?>

Save the edit and then execute:

sudo /etc/init.d/httpd restart

This command restarts the apache2 server so it is aware that PHP5 is available. Now in a browser create a new tab or window and in the URL field type:

http://localhost/phpinfo.php

A page containing information about the PHP5 installation should appear, followed by information about installed PHP5 extensions.

Finishing up

In order to install the CZ software, the installer must use the subversion client. CentOS 5.4 doesn't come with subversion , so it must be manually installed. At a terminal prompt execute:

sudo yum install mod_dav_svn subversion

After this installation completes, the LAPP stack and other software for creating a CZ clone is available. Go to the page on Configuring the LAPP stack and continue with LAPP stack conguration. You may skip the first part of the Configure Apache2 section, since you have already tested that PHP5 is correctly working. (Furthermore, document root on CentOS is different than that on Ubuntu, so there are some differences in how to carry out this test).

After completing the install of the CZ wiki software, you will return to the next section to install and configure some optional features.

Post wiki software installation and configuration

While all of the software necessary to create a CZ clone is described in the previous sections, there is other software installation and configuration required to support optional, but commonly provided features. Specifically, we must install and configure the texvc software in order for mathematical equations to display and we also must configure the email feature of the mediawiki software.

Configuring local email

In order to logon to your CZ clone, your account must have a valid email address configured. The way the CZ software judges that this condition obtains is to send you a confirmation email when you first register. This applies to all users, including the Wikiadmin user created using createAndPromote.php. So, in order to continue, we must first configure email. Normally, email is configured by a system admin to allow users to send and receive messages from other users on the internet. If your system already is configured to do this, nothing else is required. Skip the next sub-section and proceed to Setting up your email address. Otherwise, you must complete the steps in the next section.

Setting up local host email

Setting up local email on a system is not hard. Since there is a good set of instructions that describe how to do this elsewhere, they are not duplicated here. The installer should proceed to How to set up email in CentOS 5. There is one thing to note, however. Since we are setting up local email, there is no need to remove the comments from the two lines:

#inet_interfaces = all
#mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain

The configuration file is already set up for local email. The only change required is to uncomment the line:

#home_mailbox = Maildir/

so it reads:

home_mailbox = Maildir/

.

Setting up the email client

Once local email is enabled, we must set up an email agent to read the local email spool file. (If you already can send and receive email on your system, skip this section and proceed to Installing and configuring texvx.

From the Applications menu at the top left corner of the Desktop, select Internet and then Email. This displays the Evolution email client configuration window.

From the Welcome page click Forward and Forward again. The Identity page should display. In the window type <your username on the local system>@localhost. For example, if your username on the system is jdoe, then enter jdoe@localhost. Click the Forward button. The next window should be labeled Receiving Email. From the pop-down menu labeled Server Type select Maildir-format mail directories (this assumes you followed the instructions in the previous section and selected Maildir formated email). From the Configuration pop-down menu select the icon labeled Maildir. Click Forward. In the next (Receiving Options) window, select how often you want Evolution to check for email. Then click Forward. In the Sending Email window choose Sendmail from the pop-down menu. Then click Forward. In the Account Management window select the name that you want to appear for this account in Evolution. Then click Forward. In the Timezone window select your time zone. Then click Forward and Apply.

Evolution should launch and in the left-hand column will be the name you chose in the Account Management window. You should be able to send and receive email from this account.

Configuring the CZ clone with your email address

If you have used the CZ wiki at Citizendium, you should already know how to configure your email address. However, for completeness this section describes that task.

Access your local CZ clone wiki using a browser and login. At this point there is only one user - Wikiadmin, so login with this identity. When login completes, click on the Preferences tab at the top of the browser window. When your preferences window displays, enter your email address in the User profile field and click Save. A message informing you that a confirmation email has been sent appears. If Evolution is not running, start it (if it is running, click Send/Receive at the top left-hand corner). A confirmation email should appear in your account inbox. Follow its instructions. This will confirm your email address.

Installing and configuring texvx

Installing the required software

TeX support on the mediawiki software (on which the CZ software is based) requires the installation and configuration of several software packages. While for some this may go smoothly, others have had significant problems getting math equations to appear properly on wiki pages. Since this functionality is pretty basic to much of the content on CZ, there really is no option but to support it. However, be prepared for some frustration in getting this to work properly.

The software we need is not available on the software repositories that ship with CentOS 5.4. So, we need to add one. Note: third party yum software repositories can be hazardous to use. The original author of this article once added several third party repositories of questionable quality and after updating the system software, yum stopped working (yum is a python script and the update corrupted the python subsystem). So, you should be very careful when adding repositories to your yum configuration information.

In this case, we will add RPMForge. This third party repository has a good reputation and so should not be dangerous to use. However, there are no guarantees and since those installing a CZ clone on CentOS 5.4 should be experienced CentOS installers, they are expected to have the skills to get out of problems caused when a third party repository corrupts their system.

The first thing to do is to install yum priorities. In a terminal window execute:

sudo yum install yum-priorities

As always, when prompted whether you wish to continue, answer y.

Make sure priorities are enabled (they are in a fresh CentOS 5.4 install) by executing:

cat /etc/yum/pluginconf.d/priorities.conf

This should produce the following output:

[main]
enabled = 1

If enabled is not set to 1, edit the file and change it so it is.

Now, cd to /etc/yum.repos.d and edit each file by setting the priority for each repository listed. The recommended settings (given by the CentOS wiki at http://wiki.centos.org/AdditionalResources/Repositories/RPMForge) are:

[base], [addons], [updates], [extras] ... priority=1 
[centosplus],[contrib] ... priority=2
Third Party Repos such as rpmforge ... priority=N  (where N is > 10 and based on your preference)

For example, execute the following in a terminial window:

cd /etc/yum.repos.d
sudo gedit CentOS-Base.repo

When the edit window opens, you will see sections labeled by the section identifiers given above. For example:

[base]
name=CentOS-$releasever - Base
mirrorlist=http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=os
#baseurl=http://mirror.centos.org/centos/$releasever/os/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5

#released updates 
[updates]
name=CentOS-$releasever - Updates
mirrorlist=http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=updates
#baseurl=http://mirror.centos.org/centos/$releasever/updates/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5

After the gpgkey line add priority=1. These two sections should now look like:

[base]
name=CentOS-$releasever - Base
mirrorlist=http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=os
#baseurl=http://mirror.centos.org/centos/$releasever/os/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5
priority=1

#released updates 
[updates]
name=CentOS-$releasever - Updates
mirrorlist=http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=updates
#baseurl=http://mirror.centos.org/centos/$releasever/updates/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5
priority=1

Make sure you set the priorities correctly for all of the sections.

For the [centosplus],[contrib] sections, ensure the variable enabled is set to 1. That is:

enabled=1

Set the priority variable on sections in all other .repo files in the directory.

Now determine what is the machine architecture:

uname -i

This should return either i386 or x86_64. Depending on this value in a terminal window execute:

cd /tmp

i386:

sudo wget http://apt.sw.be/redhat/el5/en/i386/RPMS.dag/rpmforge-release-0.3.6-1.el5.rf.i386.rpm

x86_64:

sudo wget http://apt.sw.be/redhat/el5/en/x86_64/RPMS.dag/rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm

rpm packages are signed, so in order to use them we have to download the key for RPMForge. In a terminal window execute:

sudo rpm --import http://dag.wieers.com/rpm/packages/RPM-GPG-KEY.dag.txt

Then verify the package:

sudo rpm -K rpmforge-release-0.3.6-1.el5.rf.*.rpm

Now install the repository into the systems repository list:

sudo rpm -i rpmforge-release-0.3.6-1.el5.rf.*.rpm

Check that the installation completed properly:

yum check-update

RPMForge should appear in the list of repositories and there should be activity showing the information associated with it is updated.

Now that RPMForge is added to the repository list, we must set its priority correctly. In a terminal window execute:

cd /etc/yum.repos.d
sudo gedit rpmforge.repo

At the end of the [rpmforge] section add:

priority=11

Save the file and exit the editor.

Texvc depends on other software on the system. Particularly, ImageMagick, Ghostscript, latex and dvips must be installed. These utilities are installed by default in CentOS 5.4. To ensure this, execute:

whereis ImageMagick
whereis ghostscript

(make sure to capitalize the I and M in ImageMagick). This should result in the following output:

ImageMagick: /usr/share/man/man1/ImageMagick.1.gz

ghostscript: /usr/bin/ghostscript /etc/ghostscript /usr/lib/ghostscript /usr/share/ghostscript /usr/share/man/man1/ghostscript.1.gz

or something similar.

If one or the other of these utilities is missing, you will have to install them with yum, i.e.,

sudo yum install ImageMagick

and/or

sudo yum install ghostscript

Normally latex and dvips are not installed on a standard CentOS 5.4 system. This is easily checked with the following commands:

whereis latex
whereis dvips

Generally either both will be available or neither. To install both, in a terminal window execute:

<sudo yum install tetex tetex-fonts tetex-dvips tetex-latex

After ensuring the availablity of ImageMagick, Ghostscript, latex and dvips we must install ocaml. In a terminal window execute:

sudo yum install ocaml

Ocaml requires the availability of the gcc compiler. Check whether it exists by executing in a terminal window:

gcc

If this returns:

gcc: no input files

gcc is installed. Otherwise, execute:

sudo yum install gcc gcc-c++ autoconf automake

and answer y at the appropriate time.

We are finally in a position to build texvc. In a terminal window execute:

cd /usr/local/src/mediawiki/CZ_1_13_2/phase3/math
make

Configuring texcv

To test texcv, open a browser window in your CZ clone and create a page to edit (e.g., create a sandbox subpage for the Wikiadmin user). Edit the page and enter:

<math>\alpha^2+\beta^2=1</math>

Click Show preview. It is almost certain you will get the following error:

Failed to parse (Cannot write to or create math temp directory):

This occurs because the math/ and tmp/ directories in phase3/images is not accessible to the browser. To fix this, in a terminal window execute:

cd /usr/local/src/mediawiki/CZ_1_13_2/phase3
chmod -R 777 images

These command set the permissions on the images directory and all its subdirectories to world read-write-execute. For a production wiki installation this is probably not recommended, but since this is you personal wiki, this laxity shouldn't hurt. Now click Show Preview again. If the equation appears in properly rednered TeX, congratulations. However, you may receive the following error:

Failed to parse (Missing texvc executable; please see math/README to configure.):

If so, you need to edit LocalSettings.php and change $wgTexvc to equal $IP/math/texvc. The correct setting is:

$wgTexvc ="$IP/math/texvc";