| layout | title |
|---|---|
default |
Get Hopping! |
Software, like water, is best when fresh! This information is up to date as of 2009-06-30.
Railfrog is a simple and straightforward Content Management System for publishing websites.
The first thing you must know is that Railfrog comes in two flavours.
-
First we have Railfrog itself: this is a Ruby on Rails Engine and you will find it at http://github.com/railfrog/railfrog/tree/master.
-
Then we have the Railfrog Content Management System which is an application using the Railfrog engine to build a simple CMS. You can find it at http://github.com/railfrog/railfrogcms/tree/master.
The Railfrog engine can be integrated into any Ruby on Rails application, effectively extending the application with simple content management capabilities. You will use the Railfrog engine if you are developing Ruby on Rails applications yourself, or if you are contributing back to the Railfrog project.
The Railfrog CMS is a simple ready to use content management system. You will use this one if you just want to get started using Railfrog as standalone web publishing tool. You will probably also want to start with RailfrogCMS if you are just beggining to explore Railfrog's capabilities.
We strongly suggest that you start with RailfrogCMS, and the remainder of these instructions will assume this is the case. Once you are familiar with RailfrogCMS, using the Railfrog engine in your own projects is covered in the project documentation.
Railfrog is built on top of Ruby on Rails, and runs anywhere you can get Ruby on Rails running: that is, on most current platforms, including Windows, Mac OS/X and Linux. We expect that most people will be using a Rails-enabled web host or perhaps a VPS to deploy their application, and perhaps a laptop if you want a separate system for for testing and development.
You need to have the following:
- Ruby interpreter. We currently require Ruby version 1.8.6. Note that Ruby 1.8.7 is not currently supported. If you are on Mac OS/X or on Linux, you will most likely have Ruby available; otherwise you can get it from http://www.ruby-lang.org. If you are on Windows, the quickest way to get ruby is using the Ruby one click installer.
- RubyGems. Again, this may already be installed; on Windows it's included in the "one click installer". If you don't yet have it, see the RubyGems manual for installation instructions.
- SQLite, MySQL or PostgreSQL. There's also a long list of other databases for use with Rails which we haven't tested, please let us know if you have problems with one of these.
- Git. If you do not have git on your system, see "Install Git". On Windows we recommend the msysGit "official full installer" package. Git will be used to clone the railfrogcms repository; all required resources, including the appropriate version of Rails, will then be installed automatically.
If you want to do more than just install the Railfrog CMS and publish a website, you should be familiar with Ruby on Rails. If you are not, then you might want to go through the Getting Started with Rails guide.
Before you proceed with installation, you may want to make sure you are able to create and start a simple Ruby on Rails application. This is not required, but will reassure you that you have all the required bits and pieces installed and running (the ruby interpreter, the database, the web server, etc.). If you're on Windows, this tutorial on setting up Rails in Windows may save you some pain.
While you might have Ruby on Rails already installed on your system (or you installed it yourself following the above mentioned Getting Started guide), when you perform the following instructions to install the Railfrog CMS, you will get a specific version of Rails installed under the vendor directory. This is to ensure that Railfrog runs against the specific version of Rails that is needed (and that one might not be the same as the one that is already installed on your computer).
Railfrog setup currently requires that you use a commandline "shell" (called Command Prompt, Terminal or Konsole on various platforms) - but even if you have not done this before, it's very straightforward.
Note: In the following instructions we are prefixing all the commands with "sudo", which is what you need to gain administrator privileges on Linux and Mac. If you are on Windows, type the same commands at the "C:\>" prompt (Start | All Programs | Accessories | Command Prompt), but without the "sudo".
The Railfrog engine needs a few ruby gems.
DO THIS:
Start a commandline shell and type:
sudo gem install mime-types maruku RedCloth
Note that capitalisation is important; it's RedCloth, not redcloth.
At the time of writing, Raifrog requires Rails 2.0.5. As mentioned earlier, you'll get that version of Rails when you clone the Railfrog CMS repository following these instructions. However, another dependency that is not resolved automatically is on the corresponding version of Rake. You must ensure you have the correct version of Rake available on your system (and then that you use it when migrating the database, as explained later). You can have multiple versions installed at the same time.
DO THIS:
sudo gem install --version=0.7.3 rake
First create a working directory - for example, /Users/pris/dev or C:\dev. Change to this directory:
cd /Users/pris/dev
Use git to download the RailfrogCMS files from the github repository. The files will be downloaded into a railfrogcms directory within your working directory:
DO THIS:
git clone git://github.com/railfrog/railfrogcms.git
Now change to the railfrogcms directory:
DO THIS:
cd railfrogcms
With this step you will fetch the correct version of Rails and any other required components and install them into the vendor sudirectory of railfrogcms. Beware that this step might take a little while to download, since Rails is a large and sophisticated framework:
DO THIS:
git submodule update --init
You will notice that after this step you will have a number of new directories under vendor. In addition to vendor/rails, notice that you now have vendor/plugins/railfrog: this is the actual Railfrog engine. You'll get the latest version of the Railfrog engine that is tested to work with RailfrogCMS.
The default is to use SQLite. If you want to use MySQL or PostgreSQL instead, edit config/database.yml. (For instructions about how to do that, check the various Ruby on Rails tutorials.)
If you decide to use SQLite, then you can skip this step because you do not have to change config/database.yml: it comes preconfigured for SQLite.
Note: SQLite is just fine while you are testing and setting up, but is not recommended for heavy-duty use.
Assuming that your database connection is configured properly, you can now create the database by running the migrate script. Here you'll use Rake version 0.7.3, the version that you previously installed in Step 2.
DO THIS: (and, Yes!, you have to type those underscores...)
rake _0.7.3_ db:migrate
Start the Railfrog server:
DO THIS:
script/server
Rails will output status messages as it starts up; any problems with your setup will usually result in error messages being displayed here.
Now open a browser at http://localhost:3000/admin and you should see the Railfrog administration interface.
Note: Opening http://localhost:3000/ will show a "404 Page Not Found" error, which is correct since you haven't configured a site yet. To configure the site you'll use the administration interface.
See the wiki docs for instructions on setting up your new site. Once you have it working, you'll probably want to check the deployment documentation and deploy to a public server.
If it doesn't work for you, try asking for help on the mailing list
or on the #railfrog irc channel on irc.freenode.net.
We hope you find it useful - if you do, please consider contributing ideas, suggestions -- or even code -- to help us achieve our goal:
Design, Deploy and Maintain Websites -- with Joy!