- Do It Yourself Installation
The famous, fabled, fabulous five-minute WordPress installation is a reality when everything is configured and coordinated properly. This section walks through the steps that are often hidden from view when you use a provider with packaged installs, and highlights some of the common misfires between WordPress and MySQL instances.
The installation process is quite simple (assuming that your web server and MySQL server are already running):Download the WordPress package and install it in your web server’s directory tree, then navigate to your top-level URL and complete the configuration. One (compound) sentence describes it completely.
It’s possible and even advisable to install a fully functioning WordPress instance on your laptop or development machine, particularly if you are going to be working on the core, developing plugins or otherwise making changes that would create embarrassing failures during testing on a public web site. MacOS X comes with an Apache web server (with PHP and URL rewriting); download MySQL from mysql.com, or use a pre-packaged configuration like MAMP (mamp.info, which includes the php- MyAdmin tool) and you’ll have a self-contained development and deployment lab. For other platforms, XAMPP (www.apachefriends.org) has a neatly integrated platform stack that runs on Windows, Mac OS and Linux foundations. Having everything under one hood is a powerful option for examining failure modes, as you’ll see in the next two sections.
- Installing WordPress Files
If you download the WordPress code from wordpress.org, you’ll get a zip (or tarball) archive that expands into a directory called ‘‘wordpress.’’ The first part of a WordPress installation is to get the code into your web server’s directory structure, and ensuring you have it in the right place is a critical step. Gloss over this part and you’ll find your blog ends up with a URL like example.com/wordpress and you’ll either have to start over or e-mail ugly URLs to your friends and family. If that’s what you want, to distinguish your blog from other content on your web site or to isolate multiple blogs, choosing the filesystem layout is equally important.
Pick the top-level directory where you want to install WordPress. Most commonly, this is the root directory for your web server, and if you’re using a hosting provider it’s probably the subdirectory called public_html in the file tree. If you are using a packaged install where there’s a menu asking you for the target location, make sure you pick this top-level directory (and yes, you know that it already exists, that’s the point!); if you’re copying files from your local machine to the web server target using an FTP client, make sure you pick the right destination. The somewhat obvious move to copy the zip file to the server then unpack it will put everything into a ‘‘wordpress’’ subdirectory, and if you want your blog’s URL to be example.com rather than example.com/wordpress, move the files ‘‘up’’ one directory level before proceeding. There is a configuration option to have your WordPress installation in a subdirectory to your top-level URL, so it’s not fatal if you drop WordPress into a less-than-desirable filesystem geography. We cover that at the end of this section.
Once the WordPress files are installed, your filesystem browser should show you something like Figure 1-1, with an index.php and template wp-config-sample.php file. That’s the entirety of the WordPress system, which runs effectively within the web server's PHP interpreter.
At this point, if you're doing a manual installation, you'll want to create your own wp-config.php file by editing the sample provided and saving it in your top-level WordPress directory. As an alternative, you can navigate to your blog’s URL, and the WordPress code will realize there’s no configuration file and present you with a dialog boxes like those in Figures 1-2 and 1-3 where you can fill in the details. You'll 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 won't see this step, because the WordPress files will be extracted and the MySQL database information will be automatically inserted into a configuration file, no blogger-serviceable parts inside.
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. If you want visitors to see your blog, and to use WordPress as a content management system as we’ve described here, your best choice is to save existing content and convert it into blog 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 blog through a button or link on your extant home page. Don’t leave this to chance; if you have an index.html file and then install WordPress, you’ll 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 don’t 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 blog URL, WordPress should have completed creating the database tables, created an administrative user for your blog, and set an initial password. Upon a successful installation, you should see a box like Figure 1-4 that indicates your five minutes of famed installation are done.
- Wordpress 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’s good to have in case you run into MySQL problems later on. There’s a username and password combination included in that file, so treat it the way you’d treat other login information. On the other hand, if you’re going deep on the do-it-yourself route, this section gives you a sense of what’s likely to create confusion or consternation as you pull the pieces together.
In theory, MySQL set up for WordPress is trivial: make sure MySQL is up and running, create a Word- Press 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 like phpMyAdmin 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’re 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 prepend the name of the package or your account information to distinguish users that benefit from MySQL database co-tenancy. Again, it’s 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, we used wp_ 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.
What can go wrong between WordPress and MySQL? Three primary root causes of installation failure exist: your web server can’t even find the MySQL server to begin with, it connects to the database but can’t log in, or it logs in successfully but can’t find the named database in which to create the WordPress tables. 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 can’t 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 can’t open the socket connection to it. Here’s a simple example: When you run WordPress locally on MacOS, 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:
# ln -s /tmp/mysql.sock /var/mysql/mysql.sock
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, look 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’re 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-5:
if (!$this->dbh) {
echo(mysql_error());
$this->bail(sprintf(/*WP_I18N_DB_CONN_ERROR*/"
<h1>Error establishing a database connection</h1>
echo(mysql_error());
$this->bail(sprintf(/*WP_I18N_DB_CONN_ERROR*/"
<h1>Error establishing a database connection</h1>
The mysql_error() function is a PHP library function that spits out the error generated by the last
MySQL function called.
MySQL function called.
WordPress finds MySQL but can’t log in. Most of the time, the MySQL username or password are wrong, particularly when you have to copy some arbitrary username generated by a hosting provider. Double-check your username data, and verify that it is reflected properly in your wp-config.php file. You may also run into a password authentication issue when using MySQL 4.1 or MySQL 5.0 with some web servers’ PHP implementations; they only support the older MySQL 4.0 password hashing scheme. If this is the case, use MySQL’s OLD_PASSWORD() function to hash your WordPress user’s password in the backward-compatible format; the magic SQL incantation (at the MySQL command-line prompt or within the SQL window of MAMP) to address this is:
SET PASSWORD FOR user@host = OLD_PASSWORD(’password’);
where user@host is your WordPress database username and database hostname, and password is the
(clear text) password you provided in the configuration file.
(clear text) password you provided in the configuration file.
WordPress connects to MySQL but can’t select the database. Just because the web server can log in to the database server with your WordPress database user information doesn’t mean that there’s necessarily a database available to that user. This is another scenario best diagnosed with mysql_error() inserting it in wp-db.php where the selection error is identified:
function select($db) {
if (!@mysql_select_db($db, $this->dbh)) {
$this->ready = false;
echo(mysql_error());
$this->bail(sprintf(/*WP_I18N_DB_SELECT_DB*/’
<h1>Can’t select database</h1>
if (!@mysql_select_db($db, $this->dbh)) {
$this->ready = false;
echo(mysql_error());
$this->bail(sprintf(/*WP_I18N_DB_SELECT_DB*/’
<h1>Can’t select database</h1>
