by Aupajo



Build Status Gem Version Deploy

A calendar that combines events from different sources (such as Google Calendar and iCal feeds), and can be hosted for free on Heroku.

Sinatra GCal example

See a demo running at


  • Aggregate multiple calendars together into one stream
  • Supports iCal feeds (including Google Calendars)
  • Supports groups (see
  • Just supply a hash to create any arbitrary event
  • Supports being freely hosted on Heroku
  • 100% customisable themes with Sass and CoffeeScript support
  • Server optional (you can use the underlying calendar library by itself)
  • Rack-compatible (can be mounted inside a Rails app if needed)
  • Produces iCal feed for smartphone and desktop calendar apps to subscribe to



Simple setup

This option can host your calendar for free light use.

Sign up for a free Heroku account and click the following button:


Video tutorial

View on YouTube


Almanack is cryptographically signed. You can install it like any other gem, but you can also do so in a way that verifies the gem hasn't been tampered with.

Add my public key (if you haven’t already) as a trusted certificate and install the gem:

gem cert --add <(curl -Ls
gem install almanack -P HighSecurity

All my dependencies are cryptographically signed, so you can use the HighSecurity option. Read more.

Checksums for released gems can be verified in checksums.

Creating a calendar

Generate a new calendar with:

almanack new my-calendar

This will create a directory called my-calendar and set up your new project.

Once set up, run:

cd my-calendar
almanack start

By default, your calendar will run on http://localhost:9292.


See examples inside for iCal feeds, or static events.

Almanack.config do |config|
  config.title = 'My Calendar'
  config.theme = 'my-custom-theme'
  config.days_lookahead = 30

  # Combine sources from multiple iCal feeds
  config.add_ical_feed ''
  config.add_ical_feed ''

  # Include a downloaded iCal
  config.add_ical Pathname('downloaded-calendar.ical')

Time zone

To set your time zone, set your system's TZ environment variable.


On Heroku, you can do this with:

heroku config:set TZ=Pacific/Auckland

Custom themes

Inside your project, you can generate a new theme with:

almanack theme my-theme-name

Remember to update your to switch themes:

Almanack.config do |c|
  c.theme = 'my-theme-name'

Deploying to Heroku

Deployment works with Git and Heroku. First, add your work to git (an repository is already initialized for you when you run almanack new):

git add .
git commit -m "My awesome calendar"

With the Heroku CLI installed:

almanack deploy my-awesome-calendar

Will create and deploy

Subsequent commits can be deployed with just:

almanack deploy


Getting started

  1. Clone the repository
  2. Run bin/setup
  3. Run bin/test

Sending patches

  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature') with tests
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request