Appendix A. Installation Guide

1. Download the latest version of MySQL from http://www.mysql.com/downloads/mysql.html. Choose the latest stable release and, from the stable release page, choose the option under "Source Downloads" marked "tarball (.tar.gz)". Download the file into a directory where files can be created and there is sufficient disk space. A good location is /tmp. Change directory to this location using:

   % cd /tmp

   Note that the % character should not be typed in; this represents the Linux shell prompt and indicates that the command should be entered at the shell prompt.

2. Uncompress the package in the new installation directory by running:

   % gzip -d mysql-<version>.tar.gz

   If MySQL 3.23.42 has been downloaded, the command is:

   % gzip -d mysql-3.23.42.tar.gz

3. Un-tar the tape archive file by running:

   % tar xvf mysql-<version_number>.tar

   A list of files that are extracted is shown.

   If the version downloaded is MySQL 3.23.42, the command is:

   % tar xvf mysql-3.23.42.tar

4. Change directory to the MySQL distribution directory:

   % cd mysql-<version>

   If the version is MySQL 3.23.42, type:

   % cd mysql-3.23.42

5. Add a new Unix group account for the MySQL files:

   % groupadd mysql

6. Add a new Unix user who is a member of the newly created Unix group mysql:

   % useradd -g mysql mysql

7. Decide on an installation directory. Later, we recommend that PHP and Apache be installed in /usr/local/, so a good choice is /usr/local/mysql/. We assume throughout these steps that /usr/local/mysql/ is used; if another directory is chosen, replace /usr/local/mysql/ with the alternative choice in the remaining steps.

8. Configure the MySQL installation by running the configure script. This detects the available Linux tools and the installation environment for the MySQL configuration:

   % ./configure --prefix=/usr/local/mysql

9. Compile the MySQL DBMS:

   % make

10. Install MySQL in the location chosen in Step 7 by running the command:

    % make install

11. MySQL is now installed but isn't yet configured. Now, run the mysql_install_db script to initialize the system databases used by MySQL:

    % ./scripts/mysql_install_db

12. Change the owner of the MySQL program files to be the root user:

    % chown -R root /usr/local/mysql

13. Change the owner of the MySQL databases and log files to be the mysql user created in Step 6:

    % chown -R mysql /usr/local/mysql/var

14. Change the group of the MySQL installation files to be the mysql group:

    % chgrp -R mysql /usr/local/mysql

15. Copy the default medium-scale parameter configuration file to the default location of /etc. These parameters are read when MySQL is started. The copy command is:

    % cp support-files/my-medium.cnf /etc/my.cnf

16. Edit the configuration file and adjust the default number of maximum connections to match the default value for the maximum Apache web server connections. Using a text editor, edit the file /etc/my.cnf, and find the section beginning with the following text:

    # The MySQL server
    [mysqld]

    In this section, add the following line, then save the file, and exit the editor:

    set-variable    = max_connections=150

17. The MySQL configuration is now complete, and MySQL is ready to be started. Start the MySQL DBMS with the following command:

    % /usr/local/mysql/bin/safe_mysqld --user=mysql &

18. Check that the MySQL DBMS is running with the mysqladmin utility. The following command reports statistics about the MySQL DBMS version and usage:

    % /usr/local/mysql/bin/mysqladmin version

19. Choose and set a password for root user access to the MySQL DBMS. To set a password of secret, use:

    % /usr/local/mysql/bin/mysqladmin -uroot password secret

    Record the password for later use.

20. The MySQL server is currently running. However, when the machine is rebooted, MySQL doesn't restart automatically.

    After reboot, the command in Step 17 can be used to restart MySQL or, alternatively, this process can be made automatic. To make the process automatic, find the file rc.local (normally either in or below the directory /etc). This file is used to list locally installed software that should be run on startup. Using an editor, add the following line to the bottom of the rc.local file:

    /usr/local/mysql/bin/safe_mysqld --user=mysql &

The following steps create a user for the MySQL installation that is used in PHP scripts to access the DBMS. The user can carry out all actions required in Chapter 4 to Chapter 13 on the winestore database but has no access to other databases and can't change database access privileges. In addition, the new user can't access the DBMS from a remote server, under the assumption that the MySQL DBMS and Apache are installed on the same machine through following the instructions in this appendix.

The steps are as follows:

1. Check that MySQL is running using the password defined in Step 19 of the MySQL installation instructions:

   % /usr/local/mysql/bin/mysqladmin -psecret version

   If it isn't, then log in as the root user and start the MySQL DBMS using:

   % /usr/local/mysql/bin/safe_mysqld --user=mysql &

2. Start the MySQL command line interpreter using the same password as in the last step:

   % /usr/local/mysql/bin/mysql -psecret

3. Add a new user to the user table in the mysql database. Choose a username to replace username and a password to replace secret in the following command:

   GRANT ALL PRIVILEGES ON winestore.* TO username@localhost
   IDENTIFIED BY 'secret';

   MySQL responds with:

   Query OK, 0 rows affected (0.00 sec)

   Record the username and password for use in the examples in Chapter 3 to Chapter 13.

4. Quit the MySQL command interpreter with the command:

   quit

   MySQL responds with:

   Bye

5. Test the user created in Step 3 by running the MySQL command interpreter using the username and password:

   % /usr/local/mysql/bin/mysql -uusername -psecret

   MySQL responds with a message beginning:

   Welcome to the MySQL monitor.

6. Quit the MySQL interpreter again with:

   quit

The MySQL DBMS is now configured with a user who can access the winestore database from the database server machine localhost. The winestore database can't be tested yet; the winestore database is loaded and tested in Section 3.2 in Chapter 3.

The Apache web server is usually installed with most common Linux installations. However, we assume that it isn't installed or that an upgrade is required. In any case, it is essential that the source of Apache is available so that it can be recompiled to include PHP as a module.

1. Get the latest version of the Apache HTTP Server from http://www.apache.org/dist/httpd/. Choose the latest source code version ending in the suffix .tar.gz and save the file in the /tmp directory. However, if a secure Apache web server with SSL is required instead of the usual installation, find out which is the latest version of Apache that has SSL support by first following the instructions in the section "Installing Apache and ApacheSSL," later in this chapter.

2. Move the Apache distribution file to the base directory of the desired installation. The most common location is /usr/local/ and, assuming the distribution downloaded is Apache 1.3.20, and it was downloaded in the first step into the /tmp directory, the command is:

   % mv /tmp/apache_1.3.20.tar.gz /usr/local/

   After moving the distribution to the desired location, change the directory to that location using:

   % cd /usr/local

3. Uncompress the package in the new installation directory by running:

   % gzip -d apache_<version_number>.tar.gz

   If the distribution downloaded is Apache 1.3.20, the command is:

   % gzip -d apache_1.3.20.tar.gz

4. Un-tar the archive file by running:

   % tar xvf apache_<version_number>.tar

   The list of files extracted is shown.

   If the version downloaded was Apache 1.3.20, then the command is:

   % tar xvf apache_1.3.20.tar

5. Change directory to the Apache installation:

   % cd apache_<version_number>

   If the Apache version is 1.3.20, type:

   % cd apache_1.3.20

6. Configure the Apache installation by running the configure script. This detects the available Linux tools, the installation environment, and other details for the Apache configuration:

   % ./configure --with-layout=Apache

7. Apache has not yet been compiled or installed. The next step is to configure and build the PHP installation, and then to complete the Apache installation. Go ahead to Step 1 in Section A.1.4, and return to Step 8 when the PHP steps are complete.

8. The PHP module is now ready to be installed as part of the Apache web server. The following command reconfigures Apache to activate the PHP module support. However, the library referred to in the activate-module command doesn't yet exist (it is built in the next step):

   % ./configure --with-layout=Apache --activate-module=src/modules/php4/libphp4.a

9. Compile the Apache web server using the command:

   % make

10. Install the Apache server using the command:

    % make install

    If the installation of Apache with PHP support has been successful, the following message is shown:

    +---------------------------------------------------------+
    +
    |You now have successfully built and installed the      |
    |Apache 1.3 HTTP server. To verify that Apache actually |
    |works correctly you now should first check the         |
    |(initially created or preserved) configuration files   |
    |                                                       |
    |   /usr/local/apache/conf/httpd.conf 
    |                                                       |
    |
    | and then you should be able to immediately fire up    |
    | Apache the first time by running:                     |
    |                                                       |
    |   /usr/local/apache/bin/apachectl start
    |                                                       |
    | Thanks for using Apache.       The Apache Group       |
    |                                http://www.apache.org/ |
    +-------------------------------------------------------+

11. Edit the Apache configuration file and enable PHP script engine support for files that have the suffix .php. To do this, edit the file /usr/local/apache/conf/httpd.conf and remove the # character from the beginning of the following line:

    AddType application/x-httpd-php .php

    After removing the comment character #, save the file and exit the editor.

12. Start the Apache web server by running the command indicated by the installation process in Step 10:

    % /usr/local/apache/bin/apachectl start

    After the Apache server starts up, the following is displayed:

    /usr/local/apache/bin/apachectl start: httpd started

13. Check that the server is responding to HTTP requests by accessing it using a web browser. The simplest way to check is to use a web browser to load the URL http://localhost/. If Apache is serving correctly, an Apache test page is shown; if a previously installed Apache has been upgraded, another page may be displayed.

14. To test the PHP module, change the directory to the Apache document root:

    % cd /usr/local/apache/htdocs

15. Create a file with the name phpinfo.php using a text editor. In the file, type the following, then save the script, and exit the editor:

    <? phpinfo( ); ?>

16. Test the newly created PHP script by retrieving with a browser the following URL http://localhost/phpinfo.php.

    A web page of information about the Apache and PHP installation is shown. If the page isn't shown—and this is a common installation problem—check that Step 11 of these instructions was correctly completed. If a problem is found, edit and correct the problem, and restart Apache with the following command:

    % /usr/local/apache/bin/apachectl restart

17. Apache is now running and serving both static HTML and PHP scripts, and this installation process is complete.

    However, when the machine is rebooted, Apache will not be restarted automatically. After reboot, the command in Step 12 can be used to restart Apache or, alternatively, this process can be made automatic. To make the process automatic, find the file rc.local, normally either in or below the directory /etc. This file is used to list locally installed software that should be run on start up. Using an editor, add the following line to the bottom of the rc.local file:

    /usr/local/apache/bin/apachectl start

    If Apache needs to be stopped at any time, this can by achieved by running:

    /usr/local/apache/bin/apachectl stop

The installation of Apache, PHP, and MySQL is now complete. Instructions to optionally install the winestore source code examples can be found in the later section Section A.2.

The instructions here are for installing PHP4. PHP is bundled with most Linux installations. However, we assume PHP isn't installed or, if it is installed, that a newer version is required to replace the existing installation. If Apache is being reinstalled, PHP needs to be reinstalled also.

1. Steps 1 to 7 of the Apache installation instructions should be completed.

2. Get the latest version of PHP from http://www.php.net/downloads.php . Download the "Complete Source Code" version into the /tmp directory.

3. Choose an installation directory. If the Apache installation was begun in /usr/local/, the same location can also be used for PHP. We assume in the following steps that the base directory of the Apache installation and PHP installation are the same. Move the PHP source code file to the base directory of the desired installation. Assuming this is /usr/local/ and, assuming the distribution downloaded is PHP 4.0.6 and it was downloaded into the /tmp directory, the command is:

   % mv /tmp/php-4.0.6.tar.gz /usr/local/

   After moving the distribution to the desired location, change directory to that location using:

   % cd /usr/local

4. Uncompress the package in the new installation directory by running:

   % gzip -d php-<version_number>.tar.gz

   If the version downloaded is PHP 4.0.6, the command is:

   % gzip -d php-4.0.6.tar.gz

5. Un-tar the distribution by running:

   % tar xvf php-<version_number>.tar

   A list of files extracted is displayed.

   If the version downloaded is PHP 4.0.6, the command is:

   % tar xvf php-4.0.6.tar

6. Change directory to the PHP installation:

   % cd php-<version_number>

   If the version is PHP 4.0.6, type:

   % cd php-4.0.6

7. Configure the PHP installation by running the configure script. This detects the available Linux tools, the installation environment, adds MySQL support, and prepares for Apache integration. It assumes that MySQL has been installed previously in the directory /usr/local/mysql:

   % ./configure --with-mysql=/usr/local/mysql --with-apache=../apache_<vers>

   If Apache 1.3.20 is being used, type:

   % ./configure --with-mysql=/usr/local/mysql --with-apache=../apache_1.3.20

8. Compile the PHP scripting engine by running:

   % make

9. Now that the PHP scripting engine is built, install the PHP engine using:

   % make install

10. The PHP installation is almost complete. Now copy across the default PHP configuration file to the default location, This file, php.ini, contains the settings that control the behavior of PHP and includes, for example, how variables are initialized, how sessions are managed, and what scripting tags can be used. The command to copy the file is:

    % cp php.ini-dist /usr/local/lib/php.ini

11. Change directory to the Apache installation:

    % cd ../apache_<version_number>

    If Apache 1.3.20 is being installed, type:

    % cd ../apache_1.3.20

12. The initial configuration of the PHP scripting engine module is now complete. Return to Step 8 of the Apache installation procedure and complete the installation of Apache, which includes a test of the PHP module.