One of the recommendations that came out of our recent retrospective was to create a Blazing Cloud wiki where we would store all of our project information, best practices, how to’s, etc.  We wanted a wiki that was free, configurable/customizable and could be easily deployed to either Heroku or another hosting provider we are familiar with.  Additionally, it had to require users to log in to see content since some of the information may be confidential.

We decided to use the Redmine wiki since we have team experience using it at RailsBridge and we like that it is a Rails app.  We have a wealth of Rails knowledge here at Blazing Cloud, so we can address any issues we run into ourselves.  Also, Redmine has an large development community, is hosted on github, good documentation and an active online forum.

Redmine is many things, including a wiki. This post will focus on only on using RedMine for its wiki, specifically

• Installation
• Configuration
• Deploying to Heroku

Deploying Redmine on a development box was a snap.  However, moving it to Heroku wasn’t as straightforward.  Hopefully this post will help anyone out there looking to get a Redmine instance running on Heroku quickly.

Installation

Here is the easy part, getting Redmine running on a development box. Note that I’m running a Mac OSX 10.6, Ruby EE 1.8.7. You also need to have the Rails 2.3.5 gem installed on your system. Obviously you will also need the heroku gem to interact with Heroku. Finally you’ll need the taps gem to push your local database to Heroku.

Get a copy of Redmine to you local development machine:

[sourcecode language="plain"]
cd <some directory>
git clone http://github.com/edavis10/redmine.git
cd redmine
cp config/database.yml.example config/database.yml
vim config/database.yml   # Change it to reflect the DBMS you want to use.  It is configured to use mysql by default.
rake config/initializers/session_store.rb
rake db:migrate
script/server
[/sourcecode]

Configuration

Now that the Redmine server is running locally we need to configure the Wiki and change the security settings to meet our needs.

1. In a browser navigate to http://localhost:3000
2. Redmine comes with a built in administrator account (admin/admin). Login as admin.

Make Redmine password protected:

1. Click on Settings -> Authentication
2. Check the Authentication required checkbox and save.

Now everyone must log in to access the wiki!

Create the Redmine project and wiki

1. Click on the Administration link then New project
2. Name it whatever makes sense for your installation, I called mine Blazing Cloud Wiki, and the identifier is blazingcloudwiki.  I left all other options in their default state.
3. Now click on the “wiki” tab on the secondary navigation, not the “wiki” tab on the top navigation!
4. Notice the start page defaults to “Wiki”.  Name it whatever you like.  I kept the default name for this wiki.
5. Click save
6. Next click on the wiki tab on the top navigation
7. The “wiki” page editor should open by default.  Now add whatever content you want to the wiki home page.
8. Click save

Change the routes.rb file

1. Next you need to edit the routes.rb file
2. Replace the current “map.home” route with…

[sourcecode language="plain"]
map.home ”, :controller => ‘wiki’, :id => ’1′
[/sourcecode]
Note that the :id parameter is the database project.id assigned to the project you created above.  If you run into issues later you may want to verify that the record in the “projects” table does have ID = 1.

Restart the application server

[sourcecode language="plain"]
ctrl+c # on the console that is running the Redmine server to stop it
script/server # to restart it
[/sourcecode]

Verify that the wiki is the home page

1. In your browser log out and back in to Redmine
2. You should see the Wiki home page you created above.  Congrats, Redmine is running locally!

Deploying to Heroku

Now that we have the Redmine server running the way we want it to locally we need to make some changes before we can deploy it to Heroku.
In the “redmine” directory…

1. Edit the .gitignore file
2. Remove the line “public/plugin_assets”

Add public/plugin_assets to git

1. If the public/plugin_assets folder does not exist, create this folder and add an empty file named “README” to it. Why? Because git tracks files not folders. So to add the public/plugin_assets folder to git there needs to be a file in the folder for it to track.
2. If you need to create the README file just put some placeholder text in it. The file just needs to exist, the content does not matter.

Configure Redmine Session Handling

Redmine uses a “key” to encode cookie session data.  To deploy Redmine to Heroku you must modify the config/environment.rb file.

1. Open the config/environment.rb file and add this line within the Rails::Initializer.run do |config| block. Note that the :key should be _myapp_session and the :secret should have no spaces.

[sourcecode language="plain"]
config.action_controller.session = { :key => "_myapp_session", :secret => "somesecretphrase" }
[/sourcecode]
IMPORTANT: your secret phrase should be > 30 characters

Update your git repository

Next, add the new and updated files to your local git repopsitory:
[sourcecode language="plain"]
git add .
git commit -m "added the plugin_assets folder to git, updated the routes.rb for the new home page"
[/sourcecode]

Push to Heroku

[sourcecode language="plain"]
heroku create
git push heroku master
[/sourcecode]

Create and update the database on Heroku

Run this command to migrate the remote database
[sourcecode language="plain"]
heroku rake db:migrate
[/sourcecode]
Next push your local development database to Heroku so the project and wiki you created locally will be available to your users:
[sourcecode language="plain"]
heroku db:push #Note that this step requires you have installed the "taps" gem.
[/sourcecode]

Test on Heroku

1. Finally go to the URL that the “heroku create” command reported.
2. Log in with admin/admin and verify that the wiki is the home page.

</done!>