Figure 1.1 A clean but unconfigured WordPress installation
At this point, if you are doing a manual installation, you will want to create your own wp-config.php file by editing the provided sample file, wp-config-sample.php, and saving it in your top-level WordPress directory. As an alternative, you can navigate to your website’s URL, and the WordPress code will notice there is no configuration file. After you select your installation language, WordPress presents you with dialog boxes like those in Figures 1.2 and 1.3 where you can fill in the details. You will need the MySQL database name, database username, and some idea of the WordPress database table prefix (other than the default wp_). These lower-level details are the guts of the next section on database configuration. If you are using a hosting provider with packaged installations, you probably will not see this step because the WordPress files will be extracted and the MySQL database information will be automatically inserted into a configuration file, no end user–serviceable parts inside.
Figure 1.2 WordPress will create a new wp-config file if one does not exist.
Figure 1.3 Database configuration dialog box
What do you do if you already have HTML or other content at your target URL and you want to add WordPress to an existing site? Disposition of existing files depends on your desired first user experience upon navigating to your URL. To use WordPress as a content management system as described here, your best choice is to save existing content and convert it into new posts or pages, effectively making your previous site color commentary and context for your WordPress-driven site. Alternatively, you can install WordPress in a subdirectory, keep your existing index.html file, and direct readers to your new content through a button or link on your extant home page. Do not leave this to chance; if you have an index.html file and then install WordPress, you will have an index.php and an index.html file side by side and users will see one or the other depending upon the Directory Index configuration of your site’s web server. Actions on existing content should be informed by how much traffic that content is driving to your site: if your pages are responsible for search engine traffic, you probably do not want to disrupt the existing URLs that have been cached and should install WordPress in a subdirectory. If you feel strongly about making WordPress the wrapper around the user experience, move the content and include URL rewriting or redirection for pages that move into the WordPress world.
If you used a hosting provider’s packaged installation, or if you manually created a wp-config.php file and then navigated to your top-level URL, WordPress should have completed creating the database tables, created an administrative user for your WordPress, and set an initial password, as shown in Figure 1.4. Make sure you change the username to something different than admin.
Figure 1.4 Complete website details and set up admin user.
Upon a successful installation, you should see a box like Figure 1.5 that indicates your five minutes of famed installation is done.
Figure 1.5 Administrative information at the conclusion of a clean install
The next section covers the MySQL-WordPress configuration dance in more detail and is suitable reading even if thinking about SQL gives you hives. If you are up and running, you can skip the next section and go right to the section “Finishing Up.”
Database Configuration
If your hosting provider spun up a MySQL database and created a user for you, check your resultant wp-config.php file to gather this information. It is necessary for the MySQL probing covered in this section, and it is good to have in case you run into MySQL problems later on. There is a username and password combination included in that file, so treat it the way you would treat other login information. On the other hand, if you are going deep on the do-it-yourself route, this section gives you a sense of what is likely to create confusion or consternation as you pull the pieces together.
In theory, MySQL setup for WordPress is trivial: Make sure MySQL is up and running, create a WordPress user in MySQL, and then have that user create a database to hold the WordPress tables. You can use the MySQL command line or tools such as phpMyAdmin or Chive for these tasks, but bear in mind that MySQL has its own set of users and permissions granted to those users, distinct from those used by your (or your hosting provider’s) operating system. Once MySQL is installed, it will create a default table of users and grants, adding a root user on Unix systems that is a MySQL superuser, unrelated to the Unix root user. However, if you are attempting to connect to your MySQL instance as the MySQL root user, those connections can only be made from localhost – the same machine on which MySQL is running. If you want to learn more about MySQL permissions, the table governing grants of those permissions to users, and how MySQL users are managed, refer to the “MySQL Reference Manual” (http://dev.mysql.com/doc/) and the sections on securing the initial MySQL accounts.
No set naming conventions exist for WordPress users or databases; hosting providers will typically append the name of the package or your account information to distinguish users that benefit from MySQL database co-tenancy. Again, it is possible to have multiple databases, owned by the same user or different MySQL users, running in a single MySQL database server instance. In the example shown in Figure 1.3, wp_ is used as a prefix for both usernames and database names, at least providing a hint to the database administrator that these belong to a WordPress installation. Security best practices recommend not using wp_ as your table prefix; this is covered more in Chapter 13.
What can go wrong between WordPress and MySQL? The following are the three primary root causes of installation failure. Note that all of these conditions need to be fulfilled at installation time; there has to be some basic database structure to contain the admin user before you can log in as that admin.
● Web server cannot find MySQL. Either you have the hostname for the MySQL server noted incorrectly in the wp-config.php file, or the web server is looking for a local MySQL instance and cannot open the socket connection to it. Here is a simple example: when you run WordPress locally on Mac OS, MySQL creates the socket /tmp/mysql.sock for local connections, but the WordPress PHP code is going to look for /var/mysql/mysql.sock through the PHP engine’s MySQL module. Simply symbolically link one to the other:
The actual filesystem path to the local MySQL socket is a function of the database configuration; when it starts up, it creates the local socket. Where the PHP engine, and therefore any PHP-based applications, looks for this socket is PHP configuration dependent. If you want to figure out exactly where the mismatch is, a bit of heavy-handed printf() style debugging helps.
Edit wp-includes/wp-db.php, the set of functions that establish WordPress’s database connection. If you are seeing the “Error establishing a database connection” message during installation, insert an echo(mysql_error()); statement where the error is detected to see the details displayed along with the generic message, as shown in Figure 1.6:
The mysql_error() function is a PHP library function that spits