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.
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
- Asset Pipeline
- Application Structure
Mobile Friendly Responsive Layout
- 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
- Download tracking via Chartable (optional)
Search Engine Optimization
- Ruby (2.6.5)
- Contentful account & Contentful CLI
- Heroku account & Heroku CLI
- Chartable account (optional)
1) Clone or fork the repository and install the required Ruby gems listed in
Gemfile via Bundler.
$ git clone https://github.com/teemutammela/auralcandy.net.git $ cd auralcandy.net $ 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.
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.
$ export CONTENTFUL_DELIVERY_KEY=xyz123 $ 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
$ 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
$base_url.sub!("http://", "https://") unless settings.development?
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
https://appname.herokuapp.com. 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: https://www.auralcandy.net/sitemap.xml in
public/robots.txt to match the domain of your production site.
1) Install the required npm packages listed in
$ npm install
*.scss files in directories
/assets/sass/ will be combined and compressed into target directories
/public/stylesheets/ as configured in
$ grunt watch
production environments is set in
app/app.rb. See Sinatra documentation for further details about configuration settings.
||Classes for wrapping content objects.|
||Modules for handling routes, shared defaults, content queries and generic helpers.|
||ERB view templates and partials.|
Modules are included and registered in
app/app.rb. Modules follow Sinatra's standard modular extensions pattern.
||Contentful Delivery API client.|
||Shared defaults (brands, genres, search form parameters and footer).|
||Generic helpers, mostly for parsing strings for various purposes.|
||Legacy redirections 1).|
||Query content from Contentful and wrap it to objects (registered as helpers).|
||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
require_relative("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|
||Podcast brand (used also for site default settings)|
||Author DJ of a podcast episode|
||Recording label related to an episode|
Perform unit tests for all routes defined in
module.routing.rb using the Rack::Test library.
||Contentful Delivery API key|
||Contentful space ID|
||Sinatra environment (
$ ruby app/test/unit_tests.rb -k <API_KEY> -s <SPACE_ID> -e <ENVIRONMENT>