Skip to content

GettingStarted

Jump to bottom Edit New page
Sebastian Fiedlschuster edited this page Feb 25, 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.0  # for example, to install ruby 2.2.0
rbenv global 2.2.0  # to set ruby 2.2.0 as preferred ruby version

  • rails gem:

    rbenv rehash
gem install rails:3.2.19 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 _3.2.19_ 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'

# Development Helpers
group :development do
  gem 'pry'
  gem 'better_errors'
  gem 'binding_of_caller'
  gem 'letter_opener'
end

# Testing Environment
group :test, :development do
  gem 'guard'
  gem 'rspec-rails'
  gem 'guard-rspec'
  gem 'capybara'
  gem 'poltergeist'
  gem 'factory_girl_rails'
  gem 'database_cleaner'
  gem 'guard-spork'
  gem 'spork'
  gem 'simplecov', require: false
  gem 'fuubar'
end

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

# Loading via ajax
gem 'turbolinks', '2.2.1'

# YourPlatform
gem 'your_platform'

# 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 'redcarpet'
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"

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

You can customize your config/application.rb to your likings.

Strong Parameters

YourPlatform uses strong_parameters rather than attr_accessible. Make sure to comment out the whitelisting line in config/application.rb if you do not want to use attr_accessible as well.

# config/application.rb
# ...
# config.active_record.whitelist_attributes = true

I18n

If you don't want English as default application language, you may change it in the application configuration:

# config/application.rb
# ...
config.i18n.enforce_available_locales = true
I18n.config.enforce_available_locales = true
config.i18n.available_locales = [:de, :en]
config.i18n.default_locale = :de

Secrets

We recommend to store secret information, such as api keys or smtp credentials, in config/secrets.yml. You do not need to create this file now, but you have to set ::SECRETS in the application configuration:

# config/application.rb
# ...

require 'yaml'
secrets_file = File.expand_path('../secrets.yml', __FILE__)
if File.exists?(secrets_file)
  ::SECRETS = YAML.load(File.read(secrets_file)) 
else
  ::SECRETS = {}
end

Stage

The application can run in several stages. The stage name is used, for example, when prefixing key-value-store information. You have to set the stage in the application configuration:

# config/application.rb
# ...

# Determine a possible staging environment.
#
if __FILE__.start_with?('/var/')
  ::STAGE = __FILE__.split('/')[2] # ['my_platform', 'my_platform-master', 'my_platform-sandbox']
else
  ::STAGE = "my_platform-#{Rails.env.to_s}"
end

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 turbolinks
//= require your_platform
// ...

Stylesheet Assets

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

Remove the Rails index.html

# bash
rm public/index.html

Step 8: Providing a Logo

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

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

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