Install PHP 5 in a shared server environment, such as Dreamhost.com +

This post is adapted from one I wrote on the Dreamhost forums earlier today.

Thanks to Pikkle and others DH users who have documented their experiences -- their help was invaluable.

My comments are specifically geared to people who are not familiar with Linux and are in a little bit over their heads.

For the most part, if you use Pointbeing.net's directions, and just change the path in each step and read Pikkle's notes *before* trying to do the install, it will not be too difficult to get a basic installation working, even if you are not a Linux expert. For a simple install, I think you can just skip all the stuff in pointbeing's directions except libxml and php.

However, if you want to get some additional libraries (mcrypt, libiconv, xsl, gd's jpeg libs) working, you have have a bit more work ahead of you. Although a basic installation could be completed quickly (less than an hour), any installation involving extra libraries, even without glitches, will probably take you 1.5 to 2 hours -- much more if you start running into frustrating complications.

Let me begin by saying that because everyone's needs are different, and because things can change somewhat rapidly, it is difficult to provide a step-by-step, line-by-line "type this, then type this" account of how to do the install. This post is just intended to describe the basic principles and help you with some obstacles you might run into along the way.

Basic Concepts

Essentially, you are going to download a bunch of files into a directory, uncompress them, prepare them to be compiled, compile them ("make"), and install them. The tricky part comes when some files depend on others -- if you screw up the installation of one, then all the files that depend on it won't work, but you might not realize that immediately when it happens.

Installation

1. Telnet or SSH to your server.

2. Create a directory where you will install PHP. This should be at or near the top level of your account, in a non-web-accessible directory. Call it "bin" or "php" or something. For the rest of these instructions, I'm going to assume you called it "php." The path to it will be /home/yourusername/php/, where "yourusername" is your username and php is whatever you called the directory.

3. cd into that directory and follow the blocks of instructions for Zlib and Libiconv at pointbeing, skipping the first set of instructions about installing Apache, since Apache is already installed on your server. Wherever it says "--prefix=/usr/local/", change it to "--prefix=/home/yourusername/php"

Before downloading these files and the ones mentioned below, in most cases you should visit the official page for that software at sourceforge or xmlsoft or wherever and find out what the latest version is. Then, replace the filename in pointbeing's directions with that latest version number. You can use wget to download every file mentioned in pointbeing's instructions -- but because of the way sourceforge's mirroring/redirecting system works, it might take a minute for you to figure out the exact path of the files on the servers. You can just use your browser to begin the download, and then copy the URL of the file from your browser window and use it for your wget command. If a file won't uncompress with tar -zxvf, it's probably because you downloaded an html file instead of the actual tar.gz file, even though the url you passed to wget ended with ".tar.gz." (Test this theory by doing "more filename.tar.gz" -- if a bunch of html shows up, that's the problem.)

Note: installing Ming and the Mcrypt extensions is likely to be a big pain. Both reportedly have troubles with Debian (which is what Dreamhost runs), and Ming doesn't seem to like PHP very much, and Mcrypt doesn't always compile properly (see groundzero's note). I have been unable to install either of them successfully, although I plan to try again. Ming lets you use PHP to generate Flash presentations. Mcrypt is an encryption library.

Note: for each piece of software you download, there is a text file in its folder (available once you uncompress it) called "INSTALL". You can read this file by typing "more INSTALL" from the command line. It often gives you helpful tips for properly installing the software. (Imagine that, right?) Reading the README's is also a good idea, and gives you good info about dependencies.

Also, when you run the "configure" step for each file, you can optionally run "configure --help" first, and get an explanation of your configuration options. This helped me in step 5 below.

4. When you attempt to install LibXML2, you may run into some problems. The directions at pointbeing tell you to add flags for the path to the zlib and libiconv you installed in previous steps. *I could not get these flags to work.* Ultimately, I was only able to successfully install Libxml after leaving those flags off of the configure command. It took me a couple of hours to figure out what the problem was and that this was what was interfering with the rest of my installation. In the end, libiconv and zlib were installed on my server, and are available to PHP -- but apparently they are not properly integrated with Libxml. Since I don't plan on directly relying on either of them, I'm not really concerned about this. If someone can explain how to get libxml to work with these two libraries, and if it's even necessary, that would be great.

During the "make" process of Libxml, which takes quite a while, you will probably see hundreds of "warning" message related to a "visibility attribute directive". These can be ignored, apparently. It seems they relate to an older version of gcc, the compiler that is installed on DH's servers. It should not affect the overall success of the installation. If on the other hand Make reports "Error 1" or "Error 2" at the end of its process, your installation was not successful: LibXML was not installed, which means that LibXSLT will not be able to install either. (That was my experience, anyway.)

If you really botch things up, you can do "rm -r libxml2-2.6.16" to remove the directory you created when you uncompressed the file you downloaded. Then just uncompress the tar.gz file again and start over. This applies to all the libraries you download.

Once you successfully run "make" on LibXML, you can run the command "make tests," which will run a long (~25 minutes) series of tests on the installation. It is normal to see 6 errors during this process. When it's all over, hopefully you won't get any fatal error messages, and you can be happy that you got a good installation of libxml and can proceed.

Note that as of 12/20/04, pointbeing.net's instructions omit the final command "make install." I believe this is an error. You should run "make install" after a successful "make" or "make tests".

5. If you successfully installed libxml, libxslt should go smoothly. You may want to read the "Install" text file first to make sure you send it the right flag so it can properly find the LibXML you just installed. If you don't add the proper flag, I think it will attempt to use Dreamhost's default installation of libxml, which is too old for this version of libxslt, apparently. I set the flag for "xmllib source" or whatever it is and pointed it to /home/yourusername/php and it worked fine. This is one of those things that took me forever to figure out, but wouldn't have been a problem at all if I had just RTFM to begin with. [Update: it's not necessary to edit the configure file...it should work if you send ./configure the correct prefix.]

6. I believe you can skip the installation of libjpeg and libpng. DH already has these installed in the /usr directory on their servers, so you can just tell PHP to just look for them there, along with a bunch of other stuff. If you choose to install the jpeg library in your own directory anyway, you will get an error because it tries to install a file in /php/libjeg-nnn/man/man1. The solution is to manually create the man and man1 directories before running the make. Read the INSTALL file and set prefixes with "configure" as necessary.

7. *Other Extensions/Libraries* For my installation to be as complete as I wanted, I needed some files that were not provided by DH, or at least not provided in a recent enough version. For instance, the curl libraries. DH has both of these installed, but I couldn't get them working for some reason, so I downloaded and compiled them myself, following the basic steps outlined for each of the other extensions, and (eventually) reading the INSTALL and README files for each.

PHP.net has an extremely useful page that lists and describes every standard extension available to you, and how to install it. It tells you whether they are included in the default download of PHP, and whether they are automatically installed. (See the navbar on the left side of the page.) If you read it carefully, this will save you a lot of trouble. It tells you exactly how to reference the files in your PHP configuration command later on. It's probably a good idea to look at the list of available extensions and say, "I want that...I want that." and then read up on each one, so you don't separately download and compile them unnecessarily (like I did).

8. *Configuring PHP.* Once you have all your libraries installed, download PHP and uncompress it.

You configure PHP to prepare it to be compiled. You should run "./configure --help" first so you get an idea of what all your options are. You can also read about them at PHP.net.

Now, when you configure PHP, you could/should borrow the configuration options from me (see end of this post), or Pikkle, or pointbeing, or someone else, and then add or subtract as necessary. It's a good idea to look at the config options on a standard default installation of PHP *4* on Dreamhost, so you don't miss anything you might want. (Do this by putting "phpinfo()" on a page in your existing PHP4-powered site.) Don't forget that you can break your configuration commands across several lines, so you don't have to type everything in one long uninterrupted stream. To do this, just type a backslash at the end of the line, and hit Enter. Omit the backlash to execute the batch of commands you've entered.

So:

[machine]$: ./configure --with-pear \
> --enable-sockets \
> --enable-ftp \
> --prefix=/home/yourusername/php

(The above is not a recommended configuration: it just demonstrates syntax.) When doing the configure, you must tell the installer where to find the various files you installed earlier. You must also tell it to use the default DH files where appropriate. So, for example:

> --with-zlib-dir=/adm/usr/bin \
> --with-freetype=/usr \

I am not certain, but apparently you do not need "--with-apxs=/dh/apache/template/bin/apxs" . This tells PHP to create PHP as an Apache module, but since you will eventually be running PHP as a CGI binary, I think you should omit this. Again, I am not sure, but I skipped it. For any libraries/extensions that are not included with the default installation and for which you want to rely on the default DH files, you must tell PHP to find them. In most cases, they will be in /usr

You should (must?) also create a php.ini file that contains all the PHP preferences. It seems to me this is one of the primary reasons for compiling your own php, so it's probably a good idea to use it. Add a flag like this to your compilation script to tell PHP where to find the file once you finish the installation:

--with-config-file-path=/home/yourusername/php

(The file does not have to exist there already! You move it there later. [see below])

If you are lucky, configure will run and everything will be fine. The errors that configure generates are often specific enough to figure out what the underlying problem is: a software version is too old, or you typed in the wrong path, or one library requires another one that you didn't include, or whatever.

Once configure is done (it takes a several minutes, depending on how many options you have), you are ready to compile PHP with the Make command.

Make takes quite a while -- about 10 minutes, I think, depending -- during which time all kinds of stuff will scroll by on your screen. If you see something that says "Error," you are probably not going to have a successful compilation.

However, Make can also finish and produce **no errors** but you can still have a failed compilation! This sucks. The way to see if your installation worked is to go to the directory /home/yourusername/php/sapi/cgi . If there is a file in there called "php", then it was successful. If not, it wasn't. In other words, the whole point of the Make is to produce the binary file called "php". If it doesn't get produced, you have to do the configure and make again, which takes a frustratingly long time.

As Pikkle points out, the way to clean the installation you just messed up is to run "make distclean" from the same directory you ran make in. This will delete all the unused, malformed files you just created. I am not sure whether it is necessary to do this after each botched compile, but I did.

If your make was unsuccessful, the problem can probably be indentified by carefully going through your configuration command and trying to figure out what's missing or what's wrong.

[Remember that you can press the up arrow on your keyboard to flip through your most recent commands. This is very useful at this stage. Also, when you run make, even if it is not successful, it stores your configuration command in a file called "config.nice". I found it useful to save my original version of config.nice as "config.bak" so I could read it and make sure I didn't forget any options as I was troubleshooting later on.]

If you run make a few times and are getting nowhere, then start with the most basic configuration command possible, which Pikkle discovered is apparently:

./configure --with-libxml-dir=/home/yourusername/php

This should produce the PHP binary in sapi/cgi/ . If not, you've got worse problems than I did, and I can't really help. Just try to decipher the error messages, and retrace your steps.

It's a good feeling to see the php binary once you run the above command, because you know you are getting close.

Here's what I did from there:

1. Starting with the minimum configure command above, I ran "make" and made sure it generated the PHP binary.
2. if successful, i saved the config.nice as "config.works"
3. did "make distclean"
4. re-ran configure, adding a few likely-to-succeed options from my original "config.bak"
5. ran "make", made sure the binary was produced, and repeated these steps until i got all my options working.

This took a very long time, but it was ultimately a successful method. Below, you can see the configure command I ultimately used.

DO NOT run "make install" after make. It is not necessary and will cause an error, because it will try to install PHP to DH's Apache directory, which obviously you do not have permissions for.

9. *Installing the PHP binary.* The rest is easy - you just have to copy your PHP binary to a location where Apache can find it. Create ("mkdir") a web-accessible directory called cgi-bin within your website (e.g., /home/yourusername/yourwebsite.com/cgi-bin/)

Copy your PHP binary to that new directory using "cp /home/yourusername/php/sapi/cgi/php /home/username/yourwebsite.com/cgi-bin". cd to that web directory. Rename your PHP binary to php.cgi using "mv php php.cgi".

Important: Set the permissions on the cgi-bin directory using "chmod -R 755 cgi-bin" This allows the PHP binary to execute.

Create an .htaccess file in your main web directory (or one level up, maybe). It should look like this:

10. php.ini configuration file. When you finish your installation, you will have a file in the /home/yourusername/php directory called php.ini-recommended and php.ini-distro or something like that. I copied the php.ini-recommended to the ini path mentioned in the configuration script above, and renamed it to php.ini. I imagine this is what you are supposed to do, but I have not tested it by changing values and seeing if those values work, etc. Maybe you should use the "recommended" ini file instead. I'm sure it's documented somewhere. [Update (1/3/05):: This is indeed the recommended practice. I also got php.ini working after some problems due to compiling php with "php.ini" appended to my --with-config-file-path. After much frustration, I finally figured this out. There are two solutions: 1. Thanks to jbyers in the DH KnowledgeBase: the path you specify to PHP during "configure" should be the path to the ini file, but not include "php.ini" itself. So home/username/php not /home/username/php/php.ini. 2. You can put php.ini in your cgi-bin directory next to php.cgi. I'm not sure what the security ramifications of this are, but PHP actually checks that directory for php.ini before checking the path you specified during configuration.] It's probably also a good idea to go through the standard Dreamhost php.ini file for PHP4 and manually extract the settings you need.

11. *Test your installation*. You should already know how to do this if you just went through the trouble of creating your own PHP installation, but just create a php file with "phpinfo()" in it. Upload or save the file to a web-accessible directory, and access it with your browser. If it shows you your PHP configuration information, you have a successful installation! If it says something about authorization, make sure you've set the permissions to 755 on the cgi-bin directory and the php binary inside it.

Resources

My PHP "configure" command

Note that the path to your php.ini file points to a directory, not the .ini file itself.

phpinfo() for my installation

demo of XSL library working (uses, verbatim, the example at php.net)

Update: Here's another step-by-step description of installing PHP5 at DH. This guy even provides a tarball with all the stuff you need for a common installation, and he seems to have gotten iconv and some of the encryption stuff working.

Good luck!