Fir Isn't Rails
Fir Isn't Rails is a minimalist Ruby framework for small, static sites. It's Rack-based, so it runs on Phusion Passenger.
Warning: Alpha Release
Fir is still in alpha. It has only been lightly tested. You may very well encounter bugs. If you do, please visit Fir's GitHub repository and tell us what happened.
Installation
sudo gem intall fir
fir my_fir_site
The second command runs the Fir generator, creating a skeleton Fir site in the directory my_fir_site
.
Before we set up Passenger, let's test the site with Rackup:
cd my_fir_site
rackup config.ru -p 3000
The -p
option tells Rackup which port to listen on. This can be anything you want. (Obviously, if you're already running Rails or anything else on port 3000, you need to give Rack a different port.)
Open your browser and visit:
http://localhost:3000
You should see the home page. If you don't, something is wrong. Please visit Fir's GitHub repository and tell us what happened.
Rackup is recommended when you're developing your site locally. Press ctrl-c to kill Rackup.
Now we're ready to make it work with Passenger, which you're encouraged to use in production. At this point, the instructions become a little iffy, because so much depends on your individual system (e.g. how Apache is configured, whether you can sudo
). If you're on shared hosting, you'll probably need to contact support and have them perform some of these steps for you.
For now, let's assume you're on a Mac with the default Apache installation.
If you haven't done so, install Passenger. You should also read "Deploying a Rack-based Ruby application" in the Passenger Users' Guide.
In httpd.conf
, add a virtual host:
<VirtualHost *:80>
ServerName example.com
DocumentRoot /absolute/path/to/my_fir_site/public
RackBaseURI /
<Directory "/absolute/path/to/my_fir_site/public">
Options Indexes FollowSymLinks
Order Deny,Allow
Allow from all
</Directory>
</VirtualHost>
Make sure you edit the correct httpd.conf
! Some systems may have more than one copy of Apache installed.
Check httpd.conf
syntax and restart Apache:
sudo apachectl configtest
sudo apachectl graceful
That should do it.
If you can't make this work, there's a workaround: you can export your whole site to static HTML. See "Exporting to HTML" below.
Basic Usage
See the example app to get you started.
Editing the layout
Each page will be rendered inside application.html.erb
in the layouts
directory. (That name was chosen because it will no doubt be familiar to Rails developers.)
The current version does not support alternate layouts. Such a feature may be added in the future if there's a need.
Creating Pages
Pages live in the pages
directory, or in a subdirectory thereof. If you create a page called my-page.markdown
in pages
, Fir will map it to this URL: http://youdomain.com/my-page
. Similarly, if you create a subdirectory in pages
called subdir
, and put my-page.markdown
in there, this URL will be used: http://youdomain.com/subdir/my-page
.
Pages can have the following extensions:
.html
.html.erb
.markdown
Markdown pages get passed through ERB before the Markdown is transformed to HTML. Thus, you can make Markdown pages dynamic. Remember: ERB runs before Markdown, so whatever your ERB tags spit out will be interpreted as Markdown.
Configuring Pages
pages.yml
contains all per-page configurations. Page titles, meta descriptions, and other configs can be specified there. Each page config property will be made available to the templates as an instance variable.
Mapping URLs
You can override the default URL mapping in pages.yml
. Just add a path
property to a page, and the page will be made available under the path you specify.
Content Management
Most of us will be perfectly happy managing content by editing the files in the pages
directory. But for the sake of our clients, Fir offers another way.
Fir isn't a CMS. Instead, it exposes a minimal, RESTful API for managing content. The idea is that content should be managed with specially-designed Fir clients, rather than through Fir itself. You can see how this works by downloading the example app, booting it, and visiting /manage-content.html
in your browser. The source of that page is available on GitHub.
Fir's API uses HTTP basic authentication. The users list is stored in users.yml
. To create a user or change an existing user's password, run:
rake users:add user=username pass=password
Exporting to HTML
You can export your whole site to static HTML. If you deploy that, the only thing you'll need on your server is mod_rewrite. To export:
rake export dir=~/sites/exported_example
The export task boots a Rackup server and accesses each page to generate the cache. It then copies the cache and the rest of the public folder to the output directory. By default, Rackup runs on port 9292. You can make it use a different port like this:
rake export dir=~/sites/exported_example port=3000
Webserver Support
Fir is designed primarily for Phusion Passenger. As a Rack-based framework, it theoretically supports Mongrel, CGI, FastCGI, and a host of others.
As of this writing, Fir has only been tested with Rackup, Passenger, and CGI. If you get Fir working with anything else, please visit Fir's GitHub repository and let us know how you did it.
By the way, using CGI in production is not recommended. CGI boots a new Fir instance on every request. Fir is a pretty lightweight framework, so the load time isn't huge, but that doesn't mean CGI is a good idea. If you understand the issues with CGI and still want to use it, go ahead and take a look at dispatch.cgi
in the example site.
Unicode and Others
Fir doesn't change the character encoding of your content, so you can technically use any encoding scheme you want. That being said, UTF-8 is recommended. As always, make sure your HTML template correctly identifies the encoding scheme. (See The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets for more information.)
Don't use non-English characters in your URLs. They don't play nice with the filesystem, and they have to be percent-encoded anyway, resulting in ugly URLs. Avoid special characters other than -
and _
.