Skip to content

GettingStarted

Jump to bottom Edit New page
Sebastian Fiedlschuster edited this page May 30, 2015 · 18 revisions

Getting Started with YourPlatform

This guide will explain how to create a new rails application integrating the your_platform engine. After some costumization examples, bootstrapping the database, setting up a custom organizatial structure and some comments on deploying the application are discussed.

Step 1: Recommended Literature

Have a look at these great resources for the version management tool git and the Ruby-on-Rails framework if you are not already familiar with these tools.

Git

Ruby on Rails

Step 2: Setup the Development Machine

Due to the current popularity, this section is written for development under Mac OS X. But you can easily adapt it for development under Ubuntu Linux or similar. To make it easier to read the required package names etc., we'll set those in bold text.

Recommended Applications

Required Packages

  • XCode. Make sure to install the command-line tools from Settings > Downloads.

  • Homebrew package manager.

    Install: ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

    Then resolve issues with brew doctor.

  • git: brew install git

  • libxml2 icu4c imagemagick pwgen ghostscript as required packages for YourPlatform: brew install libxml2 icu4c imagemagick pwgen ghostscript.

  • mysql:

    brew install mysql
ln -sfv /usr/local/opt/mysql/*.plist ~/Library/LaunchAgents
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist
mysql_secure_installation

  • phantomjs for running headless specs with javascript support: brew install phantomjs.

  • redis as key-value store for caching and asynchronous processing: brew install redis.

  • rbenv as ruby version manager. This is the best way to keep your ruby version up to date without getting into conflict when maintaining several projects.

    Install as described on their github page or use homebrew.

    brew install rbenv ruby-build
rbenv install 2.2.2  # for example, to install ruby 2.2.2
rbenv global 2.2.2  # to set ruby 2.2.2 as preferred ruby version

  • rails gem:

    rbenv rehash
gem install rails bundler
rbenv rehash

Step 3: Version Control with Git

If you have not worked with git before, make sure to read some of the guides from Step 1 above. Then, configure git as follows.

Git Configuration

# zsh

# your identification
git config --global user.name 'Your Name'
git config --global user.email '[email protected]'

# recommended shortcuts
git config --global alias.st status
git config --global alias.ci commit
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.graph 'log --oneline --decorate --graph'
git config --global alias.last 'log -1 HEAD'

# additional configuration
git config --global core.editor 'emacs' # or 'vi' or 'nano' or 'gedit' or your favorite editor.
git config --global color.branch auto
git config --global color.diff auto
git config --global color.interactive auto
git config --global color.status auto

Github Account

In order to collaborate with the YourPlatform project, you'll need to signup at github.com for free.

Adding SSH Access to Github

The easiest way to access your github repositories is through SSH. For authentication, generate an ssh key and copy it to the github settings for your github account.

# zsh
ssh-keygen -t rsa -C "[email protected]"
cat ~/.ssh/id_rsa.pub

Copy this public key to https://github.com/settings/ssh.

Further information: https://help.github.com/articles/generating-ssh-keys

Step 4: Creating a New Rails App

Choose an Application Name

Now, it's time to think of a name for your project. This is a working name, which will be visible in the sourcecde. The application name, which will be seen by the users, can be changed later.

As an example, this tutorial chooses "My Platform" as application name. In camel case, this reads MyPlatform, in underscore notation my_platform. Make sure to replace these occurrances according to your application name.

Create a Rails Application

$ cd ~/rails
$ rails new my_platform --database=mysql --skip-test-unit

Initialize the Git Repository

Next, initialize the git repository.

$ git init
$ git add .
$ git commit -m "initial commit"

Create an empty repository on github called my_platform and follow the instructions there in order to connect it to your local repository.

Step 5: Adding Gems

# Gemfile
# ...
#
# Do not forget to uncomment the unicorn gem if you use it in production.
gem 'unicorn'

group :development do
  gem 'web-console', '>= 2.0'
  gem 'binding_of_caller'
  gem 'letter_opener'
end

# Security Tools
group :development, :test do
  gem 'brakeman', '>= 2.3.1'
end

# Documentation Tools
group :development, :test do
  gem 'yard'
  gem 'redcarpet'
end

# Testing Environment
group :test, :development do
  gem 'guard', '~> 2.2.5'
  gem 'guard-focus'
  gem 'rspec-rails'
  gem 'guard-rspec'
  gem 'rspec-rerun', github: 'dblock/rspec-rerun'
  gem 'capybara'
  gem 'launchy'
  gem 'factory_girl_rails', '>= 4.0.0' # '1.4.0'
  gem 'database_cleaner'
  gem 'simplecov', require: false
  gem 'email_spec'
  gem 'timecop'  # time_travel
  gem 'fuubar' # better progress bar for specs
  gem "codeclimate-test-reporter", require: nil
  gem 'poltergeist', '1.5.0'
end

# JavaScript Runtime
gem 'execjs'
gem 'therubyracer', :platform => :ruby

# YourPlatform
gem 'your_platform', github: 'fiedl/your_platform', branch: 'master'

# Temporary Forks and Overrides
gem 'gmaps4rails', '~> 2.0.2', git: 'https://github.com/fiedl/Google-Maps-for-Rails.git'
  # see: http://stackoverflow.com/questions/13807686
gem 'edit_mode', github: 'fiedl/edit_mode'
gem 'workflow_kit', github: 'fiedl/workflow_kit'
gem 'nokogiri'
gem 'json'
gem 'colored'
gem 'prawn', github: 'prawnpdf/prawn'

Then run bundle install in order to install the gems.

This is also a good point to create a new git commit.

$ git add .
$ git commit -m "adding basic gems"

Developing YourPlatform

You will probably come to a point where you would like to make changes to YourPlatform. The quick and dirty way is to override class methods in your own probject. But, it's not much harder to improve the YourPlatform project.

Therefore, just create your local copy. From there, you can easily submit pull requests later if you want.

cd ~/rails
git clone [email protected]:fiedl/your_platform.git  # or your fork
bundle config local.your_platform ~/rails/your_platform

This way, MyPlatform uses the local copy of YourPlatform in development.

This also means that, if you want to update your_platform, you also have to:

cd ~/rails/your_platform
git pull origin master

cd ~/rails/my_platform
bundle install

Step 6: Setting Up the Database

Please note: We will make use of the be alias as shortcut for bundle exec in the rest of the tutorial: alias be='bundle exec', which can be defined in your ~/.zshrc.

Make sure you have a running MySQL database running in your development machine.

You can either create a mysql user for the application, or you can give the application root access to your development database.

Either way, fill in username and password for the development and the test section in config/database.yml.

If you put real database credentials into your config/database.yml, make sure to add it to your .gitignore in order to exclude it from the repository. To make it easier for your contributors, copy your database.yml to database.example.yml and remove the passwords from the example file.

Then create the databases needed for development and testing:

be rake db:create
be rake your_platform:install:migrations   
be rake db:migrate
be rake db:test:prepare

Step 7: Connecting the Application to the YourPlatform Engine

Application Configuration

config/application.rb

You can customize your config/application.rb to your likings. But we recommend two additions:

If you have staging environments, please set the ::STAGE constant. YourPlatform will use this constant to namespace redis accordingly.

# config/application.rb
# ...

# Possible staging environment switch.
::STAGE = "my_platform-#{ENV['STAGE']}-#{Rails.env.to_s}"

In production, you probably don't want the rails error page if something goes wrong. Switch the exceptions app such that errors will be displayed with our own errors controller.

# config/application.rb
# ...

    # Exceptions: Use own app as exception handler.
    # http://railscasts.com/episodes/53-handling-exceptions-revised
    config.exceptions_app = self.routes if Rails.env.production?

Mailer Settings

In Development, an easy way to test mailing, is to use the letter_opener gem, which circumvents sending real emails and, instead, opens the generated mails in the browser.

# config/environments/development.rb
# ...

  # Mailer Settings
  config.action_mailer.delivery_method = :letter_opener
  config.action_mailer.default_url_options = {host: 'localhost', port: 3000, protocol: 'http'}

Redis

We use redis for caching. You need to tell rails the redis server for caching.

# config/environments/development.rb
# ...

  # Caching
  config.action_controller.perform_caching = true
  config.cache_store = :redis_store, 'redis://localhost:6379/0/', {expires_in: 1.day, namespace: "#{::STAGE}_cache"}

And for production:

# config/environments/production.rb
# ...

  # Caching
  config.action_controller.perform_caching = true
  config.cache_store = :redis_store, 'redis://localhost:6379/0/', {expires_in: 1.week, namespace: "#{::STAGE}_cache"}

And, if you want, also for testing:

# config/environments/test.rb
# ...
  # Caching
  config.action_controller.perform_caching = true
  config.cache_store = :redis_store, 'redis://localhost:6379/0/', {expires_in: 1.day, namespace: "#{::STAGE}_cache"}

Application Controller

The your_platform engine is not namespaced. Thus, one can't inherit the app's ApplicationController from the engine's ApplicationController. Instead, one has to reopen the class in order to extend or modify it:

# app/controllers/application_controller.rb
#
# This extends the your_platform ApplicationController
require_dependency YourPlatform::Engine.root.join('app/controllers/application_controller').to_s

class ApplicationController   # no inheritance here!
  # your additions go here, later
end

ApplicationHelper

Since your_platform has got its own ApplicationHelper, which is needed for the main app, either delete the local application helper or have it include the your_platform application helper.

# (a) remove the local application helper

# zsh
rm app/helpers/application_helper.rb
# or, (b) have the local application helper include the your_platform
# application helper.

# app/helpers/application_helper.rb
#
# This extends the your_platform ApplicationHelper
require_dependency YourPlatform::Engine.root.join('app/helpers/application_helper').to_s
module ApplicationHelper
  # ...
end

JavaScript Assets

// app/assets/javascripts/application.js
// ...
//= require jquery
//= require jquery.turbolinks
//= require jquery_ujs
//
//= require jquery.purr
//= require_boxes
//
// TODO Reintegrate gmap4rails into your_platform. We have to get away form the fork.
//= require gmaps4rails
//
//= require your_platform
//= require_tree .
//
//= require turbolinks

Stylesheet Assets

/* app/assets/stylesheets/application.css
 * ...
 *= require your_platform
 * ...
 */

Step 8: Providing a Logo

Provide a file logo.png at app/assets/images/logo.png. This will show up as a logo.

You may also want to replace the public/favicon.ico.

The standard layout uses twitter bootstrap, version 3. Therefore, if you want to replace the layout, the easiest way would be to use a twitter-bootstrap ready layout and drop it into app/views/layouts/my_layout.html.haml.

You might want to use this excellent html2haml converter.

The layout then can be set in the application controller.

# app/controllers/application_controller.rb
# ...
class ApplicationController
  layout 'my_layout'

  # ...
end

Step 9: Run the Setup

Start your rails application server:

# zsh
cd ~/rails/my_platform
be rails s
be sidekiq  # in another terminal. this will process asynchronous tasks.

Now, you should see a setup page by your_platform when you visit http://localhost:3000, where you can enter the admin account and some additional information.

Step 10: Begin your Customization

For example, you could begin by editing the terms of use text, you have accepted after completing the setup from Step 9.

Open the file app/views/terms_of_use/_terms.html.haml and fill in your terms of use:

- # app/views/terms_of_use/_terms.html.haml

%h2 Basic Terms
%p I'm a good person.

%h2 Additional Terms
%p I'm trying to behave well.

Or, you could add a method to the User model:

# app/models/user.rb

require_dependency YourPlatform::Engine.root.join('app/models_user').to_s
class User
  
  def personal_greeting
    "Hi, #{name}!"
  end
  
end

If you want to override an existing method, but call the original method using super, the easiest way to do this is using the prepend mechanism:

# app/models/user.rb

require_dependency YourPlatform::Engine.root.join('app/models_user').to_s
module UserOverrides

  # This overrides the `name` method and calls the 
  # original method using `super`.
  def name
    "Sir #{super} The Brave"
  end
  
end

class User
  prepend UserOverrides
end

Have fun ...

... and don't hesitate to send pull requests to https://github.com/fiedl/your_platform.

Add a custom footer
Add a custom sidebar
Clone this wiki locally