Installing Upgrading

Installing

Installing Forem is easy. You just need a Rails 3.1 or 3.2 application.

Specify Gem dependencies

gem 'forem', :github => 'radar/forem'

Run the installer

Ensure that you first of all have a User model and some sort of authentication system set up. We would recommend going with Devise, but it's up to you. All Forem needs is a model to link topics and posts to.

Run rails g forem:install and answer any questions that pop up. There's sensible defaults there if you don't want to answer them.

You can make Forem's forum list the root path of your application by changing the route for Forem as follows and adding an additional line:

mount Forem::Engine, :at => "/"
root :to => "forem/forums#index"

If you haven't already removed public/index.html within your Rails app, now would be a great time to do so.

Options

The installer takes some options:

• --user_class: Tells the installer what your user class is, skips the prompt.
• --no-migrate: Stops the installer automatically running the migrations.
• --current_user_helper: Tells the installer what your current_user (or similar) helper is in ApplicationController, skips the prompt.

Setting up Administration

Because Forem is a Rails engine, it doesn't work like typical forums do, where you have a pre-composed header with links to administration and logging in. This is up to you and depends on your authentication solution. On a basic Devise-powered installation, you can create a header with login and administration links like so:

<header>
  <nav>
    <% if user_signed_in? %>
      <%= link_to current_user.email, main_app.edit_user_registration_path %>
      | <%= link_to "Sign out", main_app.destroy_user_session_path, :method => :delete %>
      <% if current_user.forem_admin? %>
          | <%= link_to "Administrate", forem.admin_root_url %>
      <% end %>
    <% else %>
      <%= link_to "Sign up", main_app.new_user_registration_path %>
      | <%= link_to "Sign in", main_app.new_user_session_path %>
    <% end %>
  </nav>
</header>

You will note, however, that if you try to access the Administration page with a new user, you will be denied access. This is because your user does not have the forem_admin? flag set. You can change this in the console.

And you're done! Yaaay!

Application route helpers

When using Rails route helpers in your application layout, or in customised forem views, you need to make it clear that they are main app links.

link_to "Sign out", main_app.sign_out_path

Otherwise you will get errors resembling:

ActionView::Template::Error (undefined local variable or method `sign_out_path' for #<#Class:0x7f4f21002090:0x7f4f20ffda40>)

Conversely to access forem paths you would use:

link_to "Discussion", forem.root_path

Theming

You may also want to include the basic theme (which you can then fork and alter as you see fit)

gem 'forem-theme-base', :github => 'radar/forem-theme-base'

Run bundle install to install these gems.

If you're choosing to use a theme then you will have to put this line inside your application.css file's directives to make the theme work:

*= require "forem/{theme}/style"

Alternatively, require the stylesheet using stylesheet_link_tag:

<%= stylesheet_link_tag "forem/{theme}/style" %>

This will require you to have the Asset Pipeline feature enabled within your application, which is the default for Rails 3.1 applications.

You can read more about Theming here.

Upgrading

If you are running an old version of forem, you can upgrade to a newer version by updating your Gemfile, copying migrations, and migrating the database:

1. Update your Gemfile.

If you are version-locked, be sure to change the version number to the latest release, and then run bundle.

2. Copy the new migrations over and run them.

Run bundle exec rake railties:install:migrations FROM=forem and then bundle exec rake db:migrate. In some situations, this might not be necessary; however, this will not overwrite any files, so it is a safe operation to run.

Useful resources

• Forem – A Rails Forum Engine by Ilya Bodrov (covers installing and configuring Forem as well as some possible problems)