Important Note

There’s an issue in Merb 0.9.3 with page caching. A patch has been submitted that rectifies it, but won’t be out till the next release of Merb. In the meantime, we now have a workaround within the Feather core code that should rectify the situation.

We have also updated Feather code to use DataMapper 0.9 – however there may be some initial teething troubles as we ensure complete compatibility across the core code, and all plugins. We are seeing issues where people have out of date or old versions of some gems kicking around – follow the guide below to ensure your dependencies are up to date to hopefully resolve most issues.

If you have older versions of Merb, or DataMapper, it may well be an idea to first remove those before installing the latest versions, unless you explicitly need them for other applications.

To try and get the various versions of core dependencies required to run Feather, start by installing them as so:

  gem source -a http://gems.datamapper.org  #this line is not working!  what is the correct one?
  gem install merb --include-dependencies
  gem install data_objects do_sqlite3 do_mysql dm-core dm-more (you can leave out do_sqlite3 or do_mysql if you don't need them)
  gem install merb_helpers

There appears to be an issue with the version of ParseTree that Merb 0.9.3 pulls down, and it seems to go away by rolling back to a previous version:

  gem uninstall ParseTree (all versions)
  gem install ParseTree -v=2.0.0

Getting Started

Currently, while Feather is still so new, there is no one-step installation to get a Feather instance up and running. Instead, following these instructions will allow you to setup a Feather instance for your blog, to play with or to hack on. As we improve the setup and installation experience, this guide will be updated to reflect any changes.

• First up, grab the source – you can do this either using git, or by grabbing tarballs of the source from GitHub.

Using git:

  git clone git://github.com/mleung/feather.git
  git clone git://github.com/edraper/feather-plugins.git

Or using the tarballs:

  wget http://github.com/mleung/feather/tarball/master -O feather.tar.gz
  tar xzvf feather.tar.gz
  mv mleung-feather-b69fe94eacdd644cfdd6f84fd06454382d6942de feather
  # the actual source directory name will vary based on the most recent commit, but it'll start 'mleung-feather'

  wget http://github.com/edraper/feather-plugins/tarball/master -O feather-plugins.tar.gz
  tar xzvf feather-plugins.tar.gz
  mv edraper-feather-plugins-69612e28d81b4958efff31c7ec86b0d8491e31db feather-plugins
  # again, the actual source directory name will vary, but it'll start 'edraper-feather-plugins'

• Now you have the source, you need to setup the database configuration for your Feather instance. Run the following within the root of the Feather core code (the “feather” directory) (NOTE that you will need both the ‘merb_datamapper’, and the ‘merb_helpers’ gem in order to be able to do this):

  merb-gen
  mv config/database.yml.sample config/database.yml

This will create a sample database configuration file, and will rename it from “database.sample.yml” to “database.yml”. You’ll then need to edit it so as to setup the database configuration based on the database you are using, for example you may change the :adapter to be “sqlite3” if you want to use sqlite, or “mysql” for MySQL databases. You’ll also need to supply any further configuration required for your chosen database. Let’s say we want to use “sqlite3”; we would set the configuration as follows:

  :development: &defaults
    :adapter: sqlite3
    :database: db/development.sqlite3

  :test:
    <<: *defaults
    :database: db/test.sqlite3

  :production:
    <<: *defaults
    :database: db/production.sqlite3

• Now lets run the following (only if you are using sqlite3, this isn’t required for mysql/postgresql users):

  mkdir db
  merb-gen

This creates the “db” folder to store the sqlite3 database files, and running “merb-gen” again creates the development database.

• We now need to setup the base database schema for Feather. Plugins will manage their own schema when installing, but we need to bootstrap the initial schema for the core models within Feather. We have a custom method to migrate the core models:

  merb -i 
  irb(main):001:0> Feather::Database::initial_setup

This starts Merb in console mode, and then at the console we run “DataMapper::Persistence.auto_migrate!” to setup the default schema for Feather. FYI, the #auto_migrate! was moved to DataMapper proper in the 0.9.2 release, so if you’ve got the latest the command is “DataMapper.auto_migrate!”.

• Now everything is ready to fire it up, and take a look!

  merb

This starts the application with default settings (it’ll run using Mongrel, on port 4000). Browse to http://localhost:4000 and see the default blog! You can browse to the admin side of Feather at http://localhost:4000/admin. This will create a default user and show the admin user/pass needed to login. Once you login, you should change the admin username and password. You can also browse around the admin area and tweak other blog settings, or write your first article!

• Now you have Feather core up and running, you’ll probably want to extend your blog with some plugins. Until we get an official plugin repository up and running, the easiest way to do this is by installing the plugins locally. Please refer to the Building and Installing Plugins page for the latest update on this.

• So after playing with Feather, you may be wondering – if I do the above steps on my server to host my production blog instance, how can I setup Feather with the thin server, multiple processes, different ports etc? How can I ensure that the server will start my Feather instance upon rebooting? The easiest way to achieve this is a little Merb configuration tool I wrote called “merb-manage” (http://github.com/edraper/merb-manage). This acts a bit like “mongrel_cluster”, only it isn’t tied to a specific application server. You can install it simply using:

  gem install merb-manage

The README describes the configuration in more detail. This tool will in essence however allow you to configure your Merb application with different parameters, and also provides a startup script to ensure that the Merb application restarts when your server does. There is also a tool to start/stop/restart the configured Merb applications from the command line, making it nice and easy to get your blog setup and moved over to Feather!

This should provide a rough guide on the initial setting up of your Feather instance, and we will be trying to address many of the initial issues to provide a much easier path to setup Feather in the future. Any questions in the meantime, contact myself or Mike, and keep an eye on my blog and Mike’s blog.

NOTE: Before you try to run feather, you’re going to want to grab the tzinfo gem. Just do a sudo gem install tzinfo.