Skip to content
Source code of AuralCandy.Net - Premium House Music Podcast.
Ruby HTML JavaScript CSS
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.

AuralCandy.Net - Premium House Music Podcast

This repository contains the source code of AuralCandy.Net. Please note that this application is tailored to our needs - it's not a generic, turn-key podcast platform. This source code is released for educational purposes for anyone wishing to learn more about developing Contentful applications using Ruby and Sinatra.

This source code is distributed under Unlicense and can be used for non-commericial purposes only. Any commercial use of this source code requires explicit permission from the author. This application comes with absolutely no warranty. The author assumes no responsibility of data loss or any other unintended side-effect.


Teemu Tammela

About Us

AuralCandy.Net is a House Music podcast hosted by MK-Ultra & Mesmic - a Finnish DJ duo with a quarter century of combined experience under their belt. Over a decade running, AuralCandy.Net podcasts have reached thousands of listeners all over the world. AuralCandy.Net collaborates with over 50 record labels such as Bonzai Progressive, Piston Recordings, Tall House Digital and Vision Collective Recordings.

Table of Contents


  • Technology Stack

    • Built upon the Sinatra framework
    • Utilizes Padrino stand-alone helpers
    • Content management and delivery by Contentful
    • Ready to be deployed on Heroku (tested with heroku-18 stack)
    • Includes sample data and Rack::Test unit tests
  • Mobile Friendly Responsive Layout

  • Episode Search

    • Search by brand and genre
    • Pagination and variable items per page
    • Sort by title and date
  • Embedded Media Player

    • Saves player state in localStorage
    • Continuous playback between page loads 1)
  • Episode Landing Pages

    • Episode description
    • Genre tags (as defined in MusicRecording schema)
    • Track listing
    • Related recording labels
    • Related episodes
  • RSS/XML Feed

  • Statistics

  • Search Engine Optimization

  • Performance Optimization

    • Efficient use of caching, content compression and headers on the application level
    • Low amount of HTTP requests (27) and memory usage (~5MB)
    • JavaScript and SASS asset pipeline via Grunt
    • Full Cloudflare compatibility
  • Certification

1) Unless prevented by browser autoplay policy. See Media Engagement Index documentation for further details. Some browsers like Brave will require explicit permission from user to allow autoplay.



1) Clone or fork the repository and install the required Ruby gems listed in Gemfile via Bundler.

$ git clone
$ cd
$ bundle install

2) Login to Contentful CLI and select the target space.

$ contentful login
$ contentful space use

3) Import content models to target space.

$ contentful space import --content-file import/content-models.json

4) Import example content to target space.

$ contentful space import --content-file import/example-content.json

NOTE! Unit tests (app/test/unit_tests.rb) are designed to match the contents of example-content.json. Altering the example content in Contentful is likely to cause the unit tests to fail. It is recommended to set up two spaces (e.g. Production and Testing) and keep the unmodified example content in the latter.


Contentful Delivery API key and Space ID must be set as environment variables. In production, environment variables are set via the application settings in Heroku dashboard. In Contentful Web App, the API keys are managed via Space settings → API keys.

NOTE! Chartable ID is optional; It can be set for neither or both (local and production) environments. If ENV["CHARTABLE_ID"] is not set, @audio_url_chartable property found in class Episode simply returns the original Contentful asset URL. Chartable ID can be found at Dashboard → Integrations.

Development (Local)

$ export CONTENTFUL_SPACE_ID=xyz123
$ export CHARTABLE_ID=xyz123
$ source ~/.bashrc
$ rackup -p 9292

Application is now running at http://localhost:9292.

Alternatively, use rerun to automatically restart the application upon file save. rerun is included in the Gemfile and is installed as part of bundle install. By default rerun is set to monitor changes in the *.rb files in the app/ directory. Settings are found in the .rerun configuration file.

$ rerun rackup

Default environment is development. Set production environment via the APP_ENV variable.

$ export APP_ENV=production

NOTE! Global variable $base_url (set in app/modules/module.defaults.rb) forces HTTPS in production mode. This may break some links while running the application in production mode on a local workstation. You may disable this feature by commenting the following line in app/modules/module.defaults.rb.

$base_url.sub!("http://", "https://") unless settings.development?

Production (Heroku)

1) Create a new Heroku application via the dashboard.

2) Login to Heroku and associate the repository with the Heroku application.

$ heroku login
$ heroku git:remote -a <APP_NAME>

3) Deploy commits to production by pushing to Heroku master repository.

$ git push heroku master

The default URL of the application is More domains can be attached to the application via the Settings tab in the dashboard.

NOTE! Before deploying your site to public production environment, change the line Sitemap: in public/robots.txt to match the domain of your production site.


Asset Pipeline

1) Install the required npm packages listed in package.json.

$ npm install

2) Launch the task runner while working with JavaScripts and stylesheets. Upon file save, *.js and *.scss files in directories /assets/javascripts/ and /assets/sass/ will be combined and compressed into target directories /public/javascripts/ and /public/stylesheets/ as configured in Gruntfile.js.

$ grunt watch

Application Structure

Configuration for development and production environments is set in app/app.rb. See Sinatra documentation for further details about configuration settings.

Directory Description
app/assets JavaScripts and SASS stylesheets.
app/classes Classes for wrapping content objects.
app/modules Modules for handling routes, shared defaults, content queries and generic helpers.
app/public Static files (images, compiled JavaScripts and CSS stylesheets etc.).
app/views ERB view templates and partials.


Modules are included and registered in app/app.rb. Modules follow Sinatra's standard modular extensions pattern.

Module Description
module.client.rb Contentful Delivery API client.
module.defaults.rb Shared defaults (brands, genres, search form parameters and footer).
module.helpers.rb Generic helpers, mostly for parsing strings for various purposes.
module.legacy.rb Legacy redirections 1).
module.queries.rb Query content from Contentful and wrap it to objects (registered as helpers).
module.routing.rb Route and URL parameter handling.

1) Legacy module handles URL redirections from old AuralCandy.Net versions. You may disable this feature by removing the following lines from app/app.rb and deleting file app/modules/module.legacy.rb.


register Sinatra::Podcast::Legacy

Content Models & Classes

Classes are included in app/app.rb. Classes are wrappers for corresponding Contentful content models. Classes are used for formatting field values, handling related content by wrapping them with appropriate classes, adding helper methods as object properties and defining the accessible properties of said class.

Content Model Contentful ID Class Description
Brand brand class.brand.rb Podcast brand (used also for site default settings)
DJ author Author DJ of a podcast episode
Episode episode class.episode.rb Podcast episode
Label label class.label.rb Recording label related to an episode


Perform unit tests for all routes defined in module.routing.rb using the Rack::Test library.


Long Short Description
--key -k Contentful Delivery API key
--space -s Contentful space ID
--environment -e Sinatra environment (development or production)
$ ruby app/test/unit_tests.rb -k <API_KEY> -s <SPACE_ID> -e <ENVIRONMENT>
You can’t perform that action at this time.