Rob Seaman

Jan. 14, 2009 Update: This post applies to Mephisto 0.8. See Upgrading to Mephisto 0.8.1 for information about moving to version 0.8.1

I took what I bet is a pretty common approach to setting up Mephisto. I put a copy on my laptop, played with it just enough to get it to work and then found and followed some fairly simple instructions to install it directly on my DreamHost account. It was an easy and straight forward approach but in my case by the time I finished my installation I knew I wanted to start over. The problem was that I quickly found myself modifying too many things to get Mephisto to work and look the way I wanted. I could tell it was going to be easier for me in the long run to get the blog engine in source code control with a development and deployment environment that made it to easy tweak and update from my laptop. Since Mephisto is a Rails application I went with the common choices: maintaining the blog code in a local git repository and deploying it using Capistrano.

In this post I cover setting up a custom git branch for Mephisto along with a couple of Mephisto modifications I recommend to prepare it for deployment to a DreamHost account. Actually there's really nothing DreamHost specific here but other hosting services could require additional changes to environment files. I'll cover deployment to DreamHost using Capistrano in a my next post. If you want to take this approach then I'm assuming you're fairly technical and already have git and Rails and MySQL installed on your computer. The use of git and Rails in this post is basic but going down this maintenance and deployment path is only worthwhile if you're reasonably comfortable with both technologies.

Prep the Blog Application Repository

There are a couple of versions of Mephisto out there; the last official release was 0.8 (Drax). I started with the current master branch of the technoweenie version from github. To do the same cd to some place on your hard drive where you want mephisto installed and type:

[mac]$ git clone git://github.com/technoweenie/mephisto.git
[mac]$ cd mephisto

After the download completed, I ended up with a copy that had a last commit SHA1 ID of 14dc7e9b27ceaafa8b26627eaf20e6bafa80b3b1. If there have been any updates you'll end up with something newer than mine. I'd stick with whatever you clone but if it's newer than mine it does mean there's a chance that a change could impact the instructions in this post. If you decide you want to be sure to have the same version you can reset to that commit:

[mac]$ git reset --hard 14dc7e9b27ceaafa8b26627eaf20e6bafa80b3b1

At this point you have the Mephisto master branch. Instead of treating my copy as a fork, I set up and switched to a separate branch to keep my changes separate. If you just want to pull in and merge updates with your code then you can just work from the master. If you decided to keep your changes in custom branch like I did then you can call it whatever you want. Since my version is intended for my website, I called mine robseaman:

[mac]$ git checkout -b robseaman

When I want to apply updates from the master my plan is to switch to the master, pull the updates and then go back to the custom branch and rebase my changes to the updated master, dealing with conflicts as necessary:

[mac]$ git checkout master
[mac]$ git pull
[mac]$ git checkout robseaman
[mac]$ git rebase master

Fine, but that's for the future, let's get back to the here and now. After the clone you have a git repository that's ready to use but it's setup to maintain a blogging application for reuse by anyone on the web, independent of themes and deployment information. While you could make that work, as individual deploying a blog I felt it would be simpler to treat the whole thing as one single Rails application. To customize it that way you'll need to change the .gitignore file. For example I changed my .gitignore from:

1
2
3
4
5
6

.rake_tasks
config/database.yml
config/deploy.rb
log
tmp
themes/*

to:

1
2
3
4
5

.DS_Store
config/database.yml
log
tmp
public/assets

Here are the reasons for my choices:

• I Deleted .rake_tasks. It's not something I have, so I didn't leave it in.
• I added .DS_Store. These are hidden files containing Mac GUI information. I'm on a Mac, if you aren't then you don't need this line.
• Just like the original, I left config/database.yml out of the repository because it contains private account and password information. While it makes no sense for the database.yml to be in the Mephisto master project, for a private blog where the intention is to keep the repository local it's probably OK to check it in, especially if you only have the development and test account information. All that said, there's nothing here that really needs tracking and I like the idea that the repository can be moved around and shared without having to consider what password information it may contain.
• I Added config/deploy.rb. It contains the Capistrano deployment script. This script is something that changes so tracking it with a source code manager is beneficial. An exception would be if you end up storing passwords in the deploy.rb. In that case I'd recommend leaving it out of the repository but I do think you should avoid passwords in deploy.rb if possible. For example, if you have a password in the script because you're using it to connect using Capistrano's :password variable then switch to SSH with public key signatures or put the password in a separate recipe or the ~/.caprc file. Or, if you're dynamically building the production database.yml and including a password in your deployment script then consider not automating that part of the deployment and creating the database.yml on the server or at least consider simply uploading the production database.yml as a separate file.
• I added public/assets. In Mephisto this directory contains things like images for articles, which are more closely aligned with the database than with code. While it makes sense to maintain code locally, data and assets are created on the production server so they're not things that belong in the repository.
• I removed themes. I wanted to be able make and track changes to themes locally as part of the application and push those changes up to a web server.

When you're done commit the .gitignore changes to the new branch:

[mac]$ git commit .gitignore -m "Changed to track changes for my blog."

Put Everything in Vendor

Unfortunately Mephisto isn't keeping pace with Rails. The master branch of the 0.8 version works with Rails 2.0.2. Many hosting servers have multiple versions of Rails. If yours does and 2.0.2 exists then it's possible to set RAILS_GEM_VERSION in config/environment.rb but my preference is more in line with the vendor everything camp. Meaning I prefer to keep gems including Rails in the vendor directory to avoid potential environment issues. Here are the commands to set-up Mephisto for 2.0.2 using the vendor directory:

[mac]$ rake rails:freeze:edge RELEASE=2.0.2
[mac]$ git add .
[mac]$ git commit -a -m "Froze to Rails 2.0.2."
[mac]$ cp vendor/rails/railties/environments/boot.rb config/boot.rb
[mac]$ git commit config/boot.rb -m "Updated to Rails 2.0.2 boot.rb."

The TZInfo gem is required by Mephisto. Again, I chose to I install it into the vendor directory:

[mac]$ sudo gem install tzinfo
[mac]$ cd vendor
[mac]$ gem unpack tzinfo
[mac]$ cd ..
[mac]$ git add .
[mac]$ git commit -a -m "Put tzinfo 0.3.12 in vendor dir."

Minor Code Changes

The first code change I recommend is to change the session secret in config/environment.rb. It's the line that looks like this:

37
38

config.action_controller.session = { :session_key => "_mephisto_session", 
  :secret => "....big random string...." } 

The :secret is an application wide key string used for the cookie store and should be set to something fairly long, at least 30 characters, consisting of random numbers and letters. Rails generates a unique string for each application but since Mephisto is distributed broadly with a common key if you don't change it then Mephisto (like most open source Rails apps) is vulnerable to session hijacking. There was a discussion of this in the Ruby on Rails: Core group. I generated my :secret replacement by creating a temporary Rails application:

[mac]$ cd ..
[mac]$ rails temp

and copying the secret from temp/config/environment.rb into Mephisto's environment.rb. After the edit I deleted the temp application and committed the change:

[mac]$ rm -rf temp
[mac]$ cd mephisto
[mac]$ git commit -a -m "Changed secret from distributed version."

The only other change I recommend before using Mephisto is to comment out the multi-site enabling line in config/initializers/custom.rb unless you need multi-site support:

# Site.multi_sites_enabled = true

The multi-site feature enables a single Mephisto implementation to support multiple blogs. I think to get it to work properly you need to leave this line uncommented and do some additional setup steps. I phrased this as I think because it's not completely clear to me what the current state of this feature is. Originally the enabling line in custom.rb was commented out by default but that was changed for some reason last spring. I discovered the setting early on while playing with Mephisto on my production server when I noticed image support wasn't working. When I investigated I found my images existed but were saved in public/assets/unusedfornow.com instead of in public/assets as they were on my development server. As far as I could tell my set-up was the same in both environments, a little investigation led me to this line and after a commenting it out I had thumbnails and consistent behavior. I was likely tinkering with other things at the same time so I'm not 100% sure if I needed to do more setup or if I had the issue for some unrelated reason but since I had no need multi-site support and commenting this line out worked for me, I never looked back:

[mac]$ git commit config/initializers/custom.rb -m "Disabled multi-site support."

Program and Database Initialization

Mephisto leaves it up to you to create your database.yml but it does have an example intended to provide a starting point:

[mac]$ cp config/database.example.yml config/database.yml

Edit the database.yml and change the development database connection settings to something that will work on your local system. As always the development, test and production databases could use different DBMS software but I made sure to use the same database manager for both. SQLite may be fine for development but I like to have as much consistency as possible between development and production and I wanted to make sure it would be easy to pull production data down to my development system. DreamHost provides MySQL support so I stuck with the Mephisto's default choice of MySQL and the root user and just changed the password.

You can also set-up the test database configuration as well, I did but haven't used it yet. I don't recommend setting the production settings on your development box, although a it's little more work, it's more secure to only keep this information on the production server. I'll cover production database set-up for DreamHost in a separate deployment post. Below the production database settings are example connection set-ups and conversion connection templates. I just left them in for reference but you could delete them if you want. After the edits you can create the development database. The Rails db:create rake task needs to access the log directory, which doesn't exist yet, so do it the old fashion way using your DBMS:

[mac]$ mysqladmin -u root create -p mephisto_development

If you don't have a root password you can leave of the -p, otherwise respond with your password when prompted. Mephisto comes with it's own bootstrapping task to create the necessary folders, initialize the database and setup the default theme. For a first time set-up use this program and forget about migrations. It generates a lot of files so a git update is also required:

[mac]$ rake db:bootstrap
[mac]$ git add .
[mac]$ git commit -a -m "Ran db:bootstrap"

Go Man Go

At this point the Mephisto blogging application is ready to run on your development system. It's also in a git repository that's ready to be moved to a web hosting service. It would be a good idea before deploying to make sure it works:

[mac]$ script/server

Assuming your using Mongrel for your development environment, login to the administration portion of the site at http://localhost:3000/admin with Login: admin and Password: test and play around.