This page is stale. It’s based upon the original cedar stack, which Heroku is deprecating. This info may be still be useful, however, so I’m leaving it up. You may want to checkout out these tips in conjunction with the article below.

This page describes how to set up a WordPress blogging site, residing on Heroku.

Why? Because the site is then free for you to customize blogs exactly the way you want them… and Heroku does basic hosting for free. These instructions are intended for anyone wanting to build a site like this one. The information is specific to Mac OS. I am using Mac OS X 10.7.5.

Having an instance of WordPress up and running on Heroku is quick and simple. However, customizations you then make on Heroku such as media uploads, css adjustments, and tweaks within editor will not persist past your session, you may discover that your site customizations are all lost the next day!

As long as the dynamic content on your site are mostly text-based, you can work around this. It may take more time to set up. First, establish a working instance of WordPress on your local computer. You should make all your edits, customize, and load images on localhost. Only after you have finished making updates, commit and push your changes to Heroku.

Below describes the step-by-step instructions to two main parts:

  1. Getting WordPress working on your local computer.
  2. Pushing your WordPress version with edits to Heroku.

Part 1: Getting WordPress working on your local computer

This section discusses how to set up WordPress to run on your localhost.

Step 1: Download WordPress here.
Unzip and copy the WordPress directory to </your/working/directory>

Step 2: Install a database. Below are the procedures for installing both MySQL and PostgreSQL. Choose only one. ClearDB is a free MySQL Heroku add-on for the first 5Mb of usage, so MySQL is a logical choice. However, Postgres appears to be easier to get running. You can also add Heroku Postgres for free for development purposes.

Use brew to install packages. If you don’t have brew installed on your Mac, it’s worth getting it here. To ensure that brew installations work properly, make sure /usr/local/bin comes before /usr/bin in your PATH. (echo $PATH).

DB Option1: Installing Mysql
From your Terminal window command line, type:
$ brew install mysql

To launch when you are logged in.
$ ln -sfv /usr/local/opt/mysql/*.plist ~/Library/LaunchAgents
$ unset TMPDIR

Substitute </path/to/your/mysql> below. It should look like /usr/local/var/mysql.
$ mysql_install_db --verbose --user=`whoami` --basedir="" --datadir=</path/to/your/mysql> --tmpdir=/tmp

Set the MySQL root password with your <new-password>. To do so, start the server (You can also use the mysql.server command to start/stop the service).
$ mysqld_safe &

Issue the following command to set your MySQL root password: (MySQL sets up a unique users based upon username+host, which is why the password must be set multiple times)
$ /usr/local/opt/mysql/bin/mysqladmin -u root <new-password>
$ /usr/local/opt/mysql/bin/mysqladmin -u root -h <yourhostname> <new-password>
$ /usr/local/opt/mysql/bin/mysqladmin -u root -h <new-password>
$ /usr/local/opt/mysql/bin/mysqladmin -u root -h ::1 <new-password>

Note: If you receive an error: ‘Can’t connect to local MySQL server through socket ‘/tmp/mysql.sock‘, first check to see if you have mysql.sock on your system’. Perform the following check.
$ mdfind mysql.sock
If found, create a soft link to /tmp/mysql.sock. Otherwise,
$ sudo touch /tmp/mysql.sock
Now restart your server!
$ mysql.server restart
Go back to the instruction above to change your root password!

Add a database and setup your MySQL user on localhost, i.e. some user other than root. To do this, login to mysql as root user.
$ mysql -u root -p
mysql> use mysql;
mysql> create database <yoursitedb>;
Query OK, 1 row affected (0.00 sec)
mysql> create user '<yourusername>'@'localhost';
Query OK, 0 rows affected (0.01 sec)
mysql> grant all on <yoursitedb>.* to '<yourusername>'@'localhost';
Query OK, 0 rows affected (0.00 sec)
mysql> update user set password=PASSWORD("<youruserpassword>") where User='<yourusername>';
mysql> flush privileges;

Yeah! Your local MySQL database is ready to rock!

DB Option2: Installing Postgresql Skip this if you’re using MySQL.
From your Terminal window command line, type:
$ brew install postgres

Create Database Cluster
$ initdb /usr/local/var/postgres

Create LaunchAgents directory if it doesn’t exist already
$ mkdir -p ~/Library/LaunchAgents

Copy over setup file that allows you to Stop/Start the Postgres Server
$ cp /usr/local/Cellar/postgresql/[your postgres version]/homebrew.mxcl.postgresql.plist ~/Library/LaunchAgents/
$ launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

Use the following at your command line to create another Postgres user. You will need to supply a password.
$ createuser -W <yourusername>

In order to create your Postgres database, you will be prompted for the password for <yourusername>
$ createdb -O<yourusername> -Eutf8

Hurray! Your local Postgres database is ready to rock!

Step 3: Set up a webserver. WordPress uses php, so you’ll need a webservice which supports php. The following describes how to establish Apache webservice on localhost.

Apache comes preinstalled on Macs. However, you should get the latest version.
$ brew install apache

Apple sets WEBSHARING under System Preferences. You will need to enable web sharing using one of two options below.

  1. Select System Preferences -> Sharing -> Service "Web Sharing" "On" , or
  2. Edit /etc/apache2/httpd.conf and all remove “WEBSHARING_ON” definitions (See next section on how to open and edit this file.)

By default, PHP is not enabled on Apache, you need to make an edit in the Apache configuration file /etc/apache2/httpd.conf
$ cd /etc/apache2/
$ sudo vi httpd.conf

Type your password in order to edit the file as superuser.

Within the httpd.conf file, search for the string “php5_module“. Uncomment out the hash(#) at the beginning of the line so that it now looks like:
LoadModule php5_module libexec/apache2/libphp5.so
Save and quit the editor.

Note: httpd.conf is most likely a read-only file, so you will get an error message when you try to save the file. You will need to update file permissions before you edit the file. Type the following at the command line:
$ sudo chmod 744 httpd.conf
Edit and save changes described above. Then change permissions back with this:
$ sudo chmod 444 httpd.conf

Set up your working directory for the apache to default on localhost.
$ sudo vi /etc/apache2/users/<username>.conf

Modify your Apache user configuration.
NameVirtualHost *:80
<Directory "/your/working/directory">
Options Indexes MultiViews FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
DocumentRoot "/your/working/directory/"

Restart the webserver
$ sudo /usr/sbin/apachectl restart

Now you have Apache running with php! To test this, go to http://localhost in your browser. You should see the WordPress setup page.

Step 4: Configuring WordPress on localhost

If you have chosen MySQL, the database WordPress uses is pre-configured for MySQL. Skip down to WordPress Guided Instructions below.

If you installed PostgreSQL on your local computer, first download the PostgreSQL for WordPress (PG4WP) plugin here. You will unpack a directory called postgresql-for-wordpress. The relevant instructions under postgresql-for-wordpress/readme.txt are included below:

  1. Unzip the files from PG4WP and put the `pg4wp` directory in your `/wp-content` directory.
  2. Copy the `db.php` from the `pg4wp` directory into `wp-content`. You can modify this file to configure the database driver you wish to use.
  3. Set ‘DB_DRIVER‘ to ‘pgsql‘. You can toggle this field to set the database back to ‘mysql‘.
  4. Point your Web Browser to your WordPress installation and go through the traditional WordPress installation routine.

Go back to the browser, and type http://localhost.Follow the guided installation. Note: wherever WordPress states, “MySQL”, they mean the database of your choice.

WordPress Guided Instructions
Follow instructions as presented by WordPress in your browser. Use your username and password which you used to create your database from Step 2. For the hostname use “localhost“.

Note: If you are using MySQL, there may be problems recognizing the username. You can get around this by typing “” as the hostname. If you do this, you may have issues later accessing files from your local network, which may be problem if you’re trying to test from other devices, say, an iPad or phone. Email me if you have a fix for this. My /etc/hosts is properly defined, and postgres works fine.

Follow the WordPress guided instructions. It will guide you to cut/paste a configuration file to wf-config.php within </your/working/directory>.

You will need to set the permissions of the directory wp-content/uploads/. Note: Your Heroku hosted app will not be able to write to this directory. So later, you’ll have to push any content updates residing here. Under </your/working/directory>, do the following:
$ mkdir wp-content/uploads
Change the permissions to this directory to 777.
$ chmod 777 wp-content/uploads

Revisit http://localhost in your browser. WordPress should take you through the admin setup. Congratulations! You now have WordPress set up on your local computer.

Whew, that was just Part 1. Don’t worry, Part 2 is simpler. Before embarking on the next step, you might upload some themes to your WordPress site. Note: you will lose any blogs or posts when migrating to Heroku, but you should be able to browse and decide upon a theme. Manually download Theme zip files, and unpack to wp-content/themes.

Part 2: Push your WordPress version with edits to Heroku

Now that you are up and running, it’s time to push to heroku. If you haven’t already, install the Heroku Toolbelt here. From your command prompt, type:
$ heroku login

It will prompt you for your heroku username and password which you used to register to Heroku. Follow the quick start guide here. If you don’t have git command line, install it from here. The following will create a new git repository, add all the files recursively down from your current directory, and commit all files with the comment "initial wordpress". Type the following commands at </your/working/directory>.
$ git init
$ git add .
$ git commit -m "initial wordpress"

Use the following procedure to create a Heroku app.
$ heroku login
Enter your Heroku credentials.
Email: <yourherokuemailaddress>
Password (typing will be hidden):
Authentication successful.
$ heroku create
Creating sunny-pasture-1234... done, stack is cedar
http://sunny-pasture-1234.herokuapp.com/ | git@heroku.com:sunny-pasture-1234.git

where sunny-pasture-1234 is a Heroku haiku which identifies and allows access your application. Type the following to deploy your WordPress application to Heroku.
$ git push heroku master

WordPress now resides on Heroku under sunny-pasture-1234.herokuapp.com. Lastly, you’ll need to set up your database as a Heroku add-on. Heroku will return database configuration parameters per your application: username, password, hostname, & database name. The format is URL: dbtype://username:password:hostname/dbname. Below are examples of what you’ll see.

If you are using MySQL:
$ heroku addons:add cleardb:ignite
$ heroku config
=== sunny-pasture-1234 Config Vars
CLEARDB_DATABASE_URL: mysql://23cdab321e2345:3dac32aa@us-cdbr-east-1.cleardb.com/heroku_eacef504ad3?reconnect=true

If you are using Postgres:
$ heroku addons:add heroku-postgresql:dev
$ heroku config
=== sunny-pasture-1234 Config Vars

Update your database credentials in your wf-config.php file within your working directory. Keep a copy of your local wf-config.php. You’ll need to swap between the two configurations… Commit and merge changes with master. Push to Heroku.
$ git commit -am "Updating db configuration"
$ git push heroku master

Go to your Heroku application, e.g. http://sunny-pasture-1234.herokuapp.com/ in your browser. You should see the WordPress setup page. Congratulations! You’re done. You have now installed a WordPress website on Heroku!

Any cosmetic changes and media updates to your WordPress site should be made on your local computer. Use the last two gitcommands from your working directory to push those changes to Heroku. You’ll need to sync links to your resources library within WordPress.

Best wishes and happy hacking!