Installing P4 Chronicle on CentOS 5 -- HOWTO

Here's what it took for me to get p4chronicle-2011.1.367182 installed and running on a stock CentOS 5 64-bit machine.  If you see errors or omissions, please point them out!  If you break your stuff, ponder the virtues of having system snapshots.  If you have the ability to snapshot your system before you begin, do so, and you can skip the part about pondering its virtues after stuff is broken.

Caveat Admin
These instructions add the remi repo to your install, making it a hybrid with some consequences.  As you update to the remi version of some packages, you'll introduce some dependency issues that'll crop up when you try to update other packages that are from the main repos.  You'll also be updating PHP to version 5.3, and existing php applications on your server might get perturbed.

If you aren't comfortable with yum dependency debugging, you might want to just use the supported CentOS 6 for p4chronicle.  It's super cheap, these days, to spin-up a virtual machine .. so you might wanna test in a sandbox.  Heck, run it in a virtual machine on your laptop.

My Set-Up
Perforce Chronicle is officially supported on RHEL 6, but all my public-facing servers are still CentOS 5. Well, the included INSTALL.txt file (html version in their kb) is tailored to RHEL 6, which has a couple differences from a stock CentOS 5 server.  I'll run you through the install with the CentOS 5 additions.

For this install, I'll be using the p4d that's included in the download package, though a stand-alone daemonized p4d is recommended for "real" installs.  (That's a pretty quick side-quest, BTW.)  I'll go ahead and add a name-based virtualhost for the chronicle stuff, as recommended.  I'm going to add p4php to my web server, as recommended.  And I'll enable APC for php on my web server, despite not exactly trusting the thing.

Getting Started
Make sure that you've got httpd and php installed, running, and set to auto-start.
  sudo yum install httpd php
  sudo /etc/init.d/httpd stop   # may fail if it's not running yet.  it's okay.
  sudo /etc/init.d/httpd start  # should say "OK" or you get to fix httpd.
  sudo chkconfig httpd on       # so it'll auto-start if the system reboots.


And verify that mod_rewrite is enabled in Apache.  It is, by default, but you never know.
  grep mod_rewrite /etc/httpd/conf/httpd.conf  # make sure it's not commented out


Add a "chronicle" CNAME
We'll use that later for a name based virtual host in Apache.  How you do it is dependent on who runs your DNS.  If you run your own DNS server, you already know how to update a zone file.  (Geez I hope.)  If you use a provider like DynDNS, login to your account and poke around -- you'll be looking for "update a zone," or "add an alias," or something like that -- and aim a "chronicle" CNAME at the official name of the server you're installing on.


Download Chronicle and Present it to Apache
Download the p4chronicle tar.gz file, put it in the web server docroot, symlink p4chronicle to the current version, and then chown it to the apache user.
  # wget the bundle from perforce's server, or scp it over from wherever.
  cd /tmp       # which is where you transferred it to.  right?
  sudo mv p4chronicle-* /var/www/html
  cd /var/www/html
  sudo tar -xzf p4chronicle-*.tgz
  sudo ln -s p4chronicle-* p4chronicle
  sudo chown -R apache:apache p4chronicle p4chronicle-*

Update PHP from 5.1 to 5.3
A stock CentOS 5 machine has PHP 5.1, most likely.  You'll need to add the Remi repo to your yum config and then upgrade to the PHP 5.3 version that it provides.  If you get stuck, the CentOS wiki has a page on adding additional repos.
  /usr/sbin/php -v     # maybe you're already on 5.3 for some reason
  yum repolist         # maybe you've already got the remi repo configured
  cd /tmp              # stand back.
  wget http://rpms.famillecollet.com/enterprise/remi-release-5.rpm  # grab it.
  sudo rpm -Uvh remi-release-5.rpm                                  # add it.
  sudo yum --enablerepo=remi update php   # remi needs to be explicitly enabled.
  # there may be issues with a mysql dependency.  needs followup.  EPEL collision?
  sudo /etc/init.d/httpd restart   # so it starts using the new PHP version.

Add APC (Alternative PHP Cache) to your Web Server
They recommend that we add APC.  This is an optional step.  I've seen some annoying problems with it, but I'll go by the book, because I'm a total conformist with no free-will.
  sudo yum --enablerepo=remi install php-pecl-apc   # yoink.
  sudo /etc/init.d/httpd restart                    # all too easy.


Add P4PHP to your PHP Installation
This should provide a performance improvement over p4chronicle trying to use a normal p4 binary.  Currently, p4chronicle ships with a p4php that that's built for 32-bit, kernel 2.6 systems.  So if you're on 64-bit architecture, or otherwise weird, you get to compile your own.


32-bit users can just aim their PHP configuration at the pre-fab extension:
  sudo bash -c "echo \"; Enable the p4php 32-bit extension for p4chronicle\" >> /etc/php.d/p4php.ini"
  sudo bash -c "echo \"extension=/var/www/html/p4chronicle/p4-bin/bin.linux26x86/p4php/perforce.so;\" >> /etc/php.d/p4php.ini"
  sudo /etc/init.d/httpd restart


64-bit folks (or anyone for whom the above isn't working) need to download the the p4 API and p4php source code.  Then compile, test, and install the p4php extension.  It's not all that tricky, just lengthy.
  sudo yum --enablerepo=remi install php-devel gcc gcc-c++ make  # compiler bits
  cd /tmp                # nice and out-of-the-way
  wget ftp://ftp.perforce.com/pub/perforce/r10.2/bin.linux26x86_64/p4api.tgz
  tar -xzf p4api.tgz
  mv p4api-* p4api       # All API bits are now here in /tmp/p4api
  wget ftp://ftp.perforce.com/pub/perforce/r10.2/bin.tools/p4php.tgz
  tar -xzf p4php.tgz
  cd p4php-*
  phpize                 # man phpize: "prepare a PHP extension for compiling"
  ./configure --with-perforce=../p4api    # get set..
  make                                    # and go.  then test..
  cp /var/www/html/p4chronicle/p4-bin/bin.linux26x86/p4d . && make test
  sudo make install                       # add it to the local PHP set-up
  sudo bash -c "echo \"; Enable p4php extension for p4chronicle\" >> /etc/php.d/p4php.ini"
  sudo bash -c "echo \"extension=perforce.so\" >> /etc/php.d/p4php.ini"
  sudo /etc/init.d/httpd restart



Show Chronicle where to find p4d on 64-bit systems
There's another sneaky bit for folks on 64-bit linux.  When searching for the p4d binary, p4chronicle uses a search path that's architecture-specific.  Currently, the only included choice is linux26x86 (32-bit) but you can use a symlink to have a search for 64-bit binaries result in finding the 32-bit ones.  (The Right Way(tm), of course, is to actually make a directory and stuff real 64-bit binaries in there.  That's for the unimaginative.)
  cd /var/www/html/p4chronicle/p4-bin
  sudo ln -s bin.linux26x86 bin.linux26x86_64


Add an Apache Name-Based Virtual Host for Chronicle
This is where an apache server that's been modified from the default is going to differ, so be careful on anything that's less-than-stock.  And there's no really simple way to keep my example limited to just bash one-liners.  (I know, makes you wanna do it in bash, just to prove you can.  And you can.)  Here's what you'll need to do.
  • `sudo vi /etc/httpd/conf/httpd.conf` and uncomment the NameVirtualHost line.
    NameVirtualHost *:80
  • then, define a default virtualhost, but let it just inherit the main config. 
    <VirtualHost *:80>
    #   Just inherit from the main config.  KTHX
    </VirtualHost>
  • and finally, define a virtualhost for chronicle, which looks something like this ..
    <VirtualHost chronicle:80>
        ErrorLog logs/chronicle-error_log
        CustomLog logs/chronicle-access_log
        DocumentRoot /var/www/html/p4chronicle
        # ServerName
        # ServerAlias
        <Directory "/var/www/html/p4chronicle">
            AllowOverride All
            # Order allow,deny     # these are the default anyways.
            # Allow from all       # ditto.
        </Directory>
    </VirtualHost>

  • Save your changes to the config file,
  • and restart Apache.

  sudo /etc/init.d/httpd restart

Finish the Setup, in your Web Browser
If it all went well, you'll now be able to load the main chronicle page in a web browser.  From there, it'll walk you through the initial setup of the thing.  Just load your new "chronicle" virtualhost's main page in a browser.  From there it's simple, and goes something like this..

  • You click to start the setup.
  • It checks for all the right components.  You pass because you did it right.
  • It asks where to store content.  You say store it locally.
  • You supply it with credentials for a new admin account.
  • You probably just accept the defaults for the server name and URL.
  • When it shows the setup summary, make note of the system user and system password.
  • Done.  Have a beer.  Worry about content tomorrow.





ZOMGBROKEN1!
oh noes my yum install/update broked now!  Relax.  You're probably just seeing the side-effects of using the remi repo to update some components, then forgetting to use it when you update stuff that depends on what it installed.  For instance, you used it to upgrade PHP to 5.3, so when you upgrade anything that relies on PHP, you need to enable remi again, or you won't get the right versions.  Add `--enablerepo=remi` to your yum command.  You can blame me for this one.

selinux log messages are everywar and no installing!  selinux hates everyone, even itself, much like a Harley-Davidson owner.  Disable it .. which is what everyone else does.  It should've been that way in your kickstart.  You may blame the admin who set up the kickstart infrastructure.

teh network connections they haz teh timing-outch!  This is probably an iptables issue.  Confirm this by switching iptables off and on, and observing whether things magically worked while it was off.  (`sudo /etc/init.d/iptables stop`.)  This is extra likely if your local iptables is unusually restrictive, and you go install something like a perforce server that needs TCP port 1666 open.  Blame the security guys.

can haz CVS not scary-new perforces?  Actually, I'll bet you could.  If you are that attached to the old familiar CVS system, you go right ahead and emulate the Perforce API in front of a CVS repository.  This would make a pretty spiffy and retro hackday project .. like steampunk .. except steamcode.  Blame those jerks at CollabNet for rocking the boat.

PHP modyule trys for killing me but witch?  Yeah, it happens.  Sneaky little bastards.  See what all has ini files in /etc/php.d/ and then gzip the first one.  (In this example, that's APC, so `sudo gzip /etc/php.d/apc.ini`.)  Then restart httpd.  Is the problem still there?  If it's still there, gunzip that first ini file, then gzip the next one in the directory.  Restart httpd.  Still there?  You get the idea.  Blame the communists who invented free software in the first place.

glaarghleflarrrrghies!  Stop.  Breathe.  Go back a section or two from where you got to and double-check your work.  Search the Perforce KB.  Try some Googles.  It's only a fricken CMS, and drupal will die soon enough on its own, thus making more people write instructions for p4chronicle.  Problem solved.  Blame Ritalin.

2 comments:

  1. Thanks very much for this writeup -- very thorough! (I wrote most of the INSTALL.txt contents, so I'm curious how folks are faring with its installation)

    Regarding the 32 vs 64 bit binaries issue, Chronicle 2011.1 does come in a flavour with 64-bit binaries. In the future, we're looking at providing just one distributable with all supported binaries included to avoid these kinds of problems.

    If you have any further questions or feedback, please let support@perforce.com know.

    Cheers!
    -Marc (@p4marc)

    ReplyDelete