The following instructions are for installing WordPress 1.2.1 on a website hosted by DreamHost. If you notice an error or missing info, I would appreciate it if you would email me at robert AT wombatnation DOT com.

Any text in bold should be replaced with your specific website domain name, database name, database user, database password, WordPress username, etc. Obviously, I did not really use hardtoguesspassword literally as my password, and neither should you.

Also, these notes assume you are using an ssh client to get shell access to your DreamHost server. That means your DreamHost user account must have been granted shell access, not just the default level of FTP access. If you need to make this change, it will take about 15 minutes to take effect, so do it now! While you can install WordPress with just an FTP client, it is more work and these notes won't be as useful to you. Learn to love the shell. See the Basic Shell Commands section below for a quick reference.

These instructions also assume you want your blog to be rooted in a directory separate from the WordPress installation directory. This is a new feature in WordPress 1.2.

Create MySQL Subdomain, Database, and Database User

New MySQL domains and databases take about an hour to become active on DreamHost, so do this step as early as possible. MySQL domains and databases are created in the MySQL control panel, in the "Goodies" section. MySQL domains are special; don't create your MySQL domain in the regular DreamHost domain control panel.

  1. Use the DreamHost MySQL control panel to add a new database. Give it a name you will remember, e.g., wpblogdb. The name you choose has to be unique across the DreamHost shared servers, though.
  2. Then use the DreamHost MySQL control panel to add mysql.domainname.com as a MySQL hostname for your database. If you already have a database using that sub-domain, use something like mysqlwp.domainname.com.
  3. Create a new user, e.g., dbadmin, for this database.
  4. Give the dbadmin user a password - hardtoguesspassword

Your database will not be usable with WordPress until the Status column says "active" for both the user and the MySQL hostname.

Download and Unpack WordPress Installation File

While you can use Telnet instead of ssh to connect to your server, ssh is secure and just as easy to use. On Windows, I use PuTTY. On Mac OS X, I use Fugu or the command line. On Linux, I use ssh on the command line, as Linus intended.

The wget command below will download the latest stable release of WordPress. If for some unlikely reason the download fails, you can always download it from the regular WordPress download page.

  1. Connect to domainname.com using ssh
  2. cd domainname.com [This puts you in the root directory of your website]
  3. wget http://wordpress.org/latest.tar.gz
  4. tar xvzf latest.tar.gz

You will now have a new directory called wordpress.

WARNING: Do not place the wordpress directory and your blog directory in sibling directories. For example, example.com/blog/ and example.com/wordpress/ will result in you not being able to login after you logout the first time. There is more info about this bug/limitation on the WordPress Beta Discussion forum. This problem may have fixed since the 1.2 beta, but I'm not sure.

Two configurations I have used successfully are:

Edit Configuration File

I use Emacs as my editor. Use whichever editor you know well. I added simplified Emacs instructions in case you haven't used it before.

  1. cd wordpress
  2. cp wp-config-sample.php wp-config.php
  3. emacs wp-config.php
  4. Set value of 'DB_NAME' to wpblogdb
  5. Set value of 'DB_USER' to dbadmin
  6. Set value of 'DB_PASSWORD' to hardtoguesspassword
  7. Set value of 'DB_HOST' to mysql.domainname.com
  8. Press ctrl-x then press ctrl-s then press ctrl-x then press ctrl-c to save and exit Emacs

Run the Installer

In a web browser:

  1. Load http://www.domainname.com/wordpress/wp-admin/install.php in the browser
  2. Click on the link that says "let's go".
  3. If step 1 succeeded, the next to last line will say "All done!". Click the link that says "Step 2".
  4. Assuming the URL at the bottom of the Step 2 page correctly points to the WordPress install directory (not the blog directory), click the button labeled "Step 3...". Otherwise, correct the URL before continuing.
  5. A new user named admin will have been created for you and assigned a random password. Write down the password on a piece of paper. You will change it very soon.

After you click the "login" link, you should see a box in the center of the browser window that says WordPress followed by a couple links and some edit boxes for login info. If you just see this text in the top left corner of the browser window without the surrounding box, the URL for your WordPress install was probably wrong. You will likely need to empty or drop the tables (see Troubleshooting section below) and start over with the install.php script.

Otherwise, log in as admin with the random password you wrote down.

Change Admin Password

Click on the link in the top menu bar titled "Profile". After the new page appears, enter a new password in the bottom two edit boxes to replace the random password you previously wrote down. You will also need to supply an email address before you can udate the profile for the admin user. Click the Update Profile button after making the changes. Log back in with the new password.

Or, assuming you liked the random password and didn't write it down where evil doers could access it, skip this step.

Create New User

Click on the link in the top menu bar titled "Users". Add a new user. On the next screen, click the plus sign once so you will be able to create and edit posts. Click it twice more to take the access level up to 3 if you want to have admin privileges under the new username. Crank the level up to 9 if you want this user to effectively have site admin privileges.

Logout as the admin user and log back in as the user you just created. Usernames are case sensitive.

Secure the Files

Perhaps I'm a little paranoid about security, as the odds that skipping the instructions in this section will result in your site getting hacked are very, very, very small. My fellow paranoids are welcome to follow along, though.

On my system's install of Emacs, the file you are editing is always backed up with the same name appended with a ~. For example, after editing and saving wp-config.php with Emacs, you will find a wp-config.php~ file in the directory. Use

rm *~ [Execute this statement from a ssh session when in the wordpress directory]

to delete these backup files from the wordpress directory. If you use a different editor, like vim, pico, or nano, make sure you delete the backup files from your server immediately.

Otherwise, anyone who knows your directory structure could request copies of the backup files with an appropriately constructed URL, e.g., http://www.domainname.com/wordpress/wp-config.php~. Normally, a cgi or php file will be executed as a script on the server rather than sent back to the web browser as a text file. However, a .php~ file looks an ordinary text file to the web server.

You can slightly improve the security of your WordPress installation by protecting the wp-config.php file with a .htaccess file for the directory. More importantly, though, the following .htaccess file will protect wp-config.php~ in case you ever forget to delete it.

  1. emacs .htaccess [Execute this statement from a ssh session when in the wordpress directory]
  2. Type the following lines exactly as specified:
  3. <FilesMatch "wp-config.php[~]*">
        <Limit GET>
        deny from all
        </Limit>
    </FilesMatch>
    
  4. Press ctrl-x then press ctrl-s then press ctrl-x then press ctrl-c to save and exit Emacs

To delete the .htaccess~ backup files created by Emacs, you need to put a . in front of the *.

rm .*~ [Execute this statement from a ssh session when in the wordpress directory]

Configure Your Weblog

The WordPress website has clear instructions for configuring your install to publish your blog somewhere other than the install directory. You can ignore the step regarding database details. Remember not to publish your blog into a sibling directory of your wordpress install directory.

While you are on the Options page, I recommend unchecking the "Anyone can register" checkbox. Remember to click the Update Options at the bottom on each page where you make a change.

In the second row of tabs, click on Reading. I recommend changing feeds to "full text" and checking the gzip box at the bottom.

Preempt Comment Spam (optional)

Once the spammers discover your blog, they will start posting comments that link to their websites. By creating inbound links to their sites, they hope to increase their Google pagerank. You get stuck with links offering to increase the size of a part of the human anatomy you may not even have.

One easy step to take right now is to change the name of the PHP file used to post comments to your blog. You can find the file in the wordpress directory. Rename it to something else, e.g.,

$ mv wp-comments-post.php wp-comments-alt-post.php

Then, edit wp-comments.php, wp-comments-popup.php, and wp-comments-reply.php to use the new filename. Be sure to rename (i.e., use the mv command) instead of copy the wp-comments-post.php file. If you leave the file on your server with the original, the spammers can obviously still access it.

Another cool trick is to allow the wp-comments-post.php to be called only when the referer URL is from your website. Obviously, spammers can forge this, too, but no solution is going to be perfect. The goal is to create enough of a deterrent that the spammer goes on to the next blog. Add the following to the .htaccess file in the root directory of your website, or at least at the root level of your blog (i.e., where index.php lives).

RewriteCond %{HTTP_REFERER} "!^http://www.domainname.com/.*$" [NC]
RewriteCond %{REQUEST_URI} ".*wp-comments-alt-post.php$"
RewriteRule .* - [F]

More Resources for fighting comment spam:

Troubleshooting

The first thing I almost always do is copy the text of the error message into Google or some other comprehensive search engine and search around to see if some other poor sap has run into the same problem. Then I search the WordPress support forums.


Database Problems

If you mess up the database tables during an initial install, you can drop them or empty them pretty easily.

  1. Load http://www.domainname.com/dh_phpmyadmin/mysql.domainname.com/ in a web browser [This is the phpmyadmin interface to MySQL]
  2. Log in as dbadmin with password hardtoguesspassword
  3. Under the column with the heading "MySQL", click on "Databases"
  4. Click on the name of your database
  5. Click the link that says "Drop" in each row

You could also have clicked the link that said "empty" for each row, but then you would see a bunch of errors (which should just be warnings) about the tables already existing when you rerun install.php. Either way, you should be able to run install.php again without a problem.

Also, if you are getting errors about connecting to the database, use the above instructions for logging into WordPress. Make sure you use the same user name and password that you are using in wp-config.php. I even recommend copying and pasting the text to make sure you are doing the exact same thing. If you can't login through phpMyAdmin, then you must have entered the wrong database connection info into wp-config.php.


Login Problems

On one of my WordPress 1.2 RC1 installs, I always had trouble logging out as one user and logging back in as another. The problem is that I could never even logout as the first user. The temporary fix is to delete the web browser cookies that WordPress creates. The real fix is to upgrade to WordPress 1.2.1. The WordPress development team backported a fix from the upcoming 1.3 release to 1.2.1.

Basic Shell Commands

When you use ssh to connect to your server, you have what is called "shell access". Here are a couple of handy shell commands.

Credits

Thanks to everyone who has provided corrections or suggestions for improvements to these notes. The instructions are much better due to all of your contributions. Also, I appreciate all the kind emails I have received from people who have found these notes helpful. These notes are part of my payback to the Internet community for all the help I've received over the years due to other people being willing to post helpful instructions and answers on searchable websites.