V2 High Level Design Notes

V2Master

• Contents

  1. V2 High Level Design Notes
  2. Introduction
  3. Ruby On Rails Resources
     1. On-Line Reference Material
     2. Books
  4. Source Code Management
     1. Repositories
        1. V2 Related git Repositories
        2. Creating a New git Repository
        3. Pushing a git Repository to the Git Server
     2. Use of Branches
  5. Application Services
     1. Logging
        1. Configuring Logging
     2. Application Configuration
     3. HTML Templates
     4. CSS Templates
     5. Database Server
        1. Configuring MySQL
     6. Authentication
     7. JavaScript Libraries
     8. Internationalization
     9. Automated Unit and Integration Testing
     10. Background Process (Event Daemon)
     11. PDF File Generation
  6. Application Architecture
  7. User Access Modeling
     1. Definitions
     2. Requirements

Introduction

This section contains notes for the design and implementation of V2, in particular notes about how to use the technology stack.

Ruby On Rails Resources

On-Line Reference Material

1. Rails API documentation - http://api.rubyonrails.org

2. Rails Guides - http://guides.rubyonrails.org

Books

1. Ruby on Rails 3 Tutorial, by Michael Hartl - A beginning book with an emphasis on automated unit and integration testing with RSpec -

2. The Rails 3 Way, by David H. Hansson - An advanced book with in-depth descriptions of most Rails related topics

   1. Section 11.20 - Internationalization using the I18n Ruby GEM

   2. Chapter 14.2 - Authentication using Devise
   3. Chapter 18 - RSpec

Source Code Management

1. Use git

Repositories

1. Server: git.softxs.ch
2. Directory: /home/bit/gitroot

3. HTTP access: http://git.softxs.ch/projects

V2 Related git Repositories

1. TODO mapps - Master Application Payment System Application source code

2. TODO v2 - V2 application code

3. TODO skeleton - Skeleton Application source code

4. TODO proto-ds - Darren Starsmore prototype

5. sample-app-ah - Alan Hodgkinson sample_app source code, from Hartl book

Creating a New git Repository

1. Repositories should have the suffix .git

2. Repositories should have group git and be group writable

The following example shows how to make a new git repository named new-name

• ssh git.softxs.ch
  
  cd /home/git/gitroot
  
  mkdir new-name.git
  chgrp git new-name.git
  chmod g+w new-name.git
  
  cd new-name.git
  
  git init --bare --shared
  
  echo 'Short one-line description of new-name project' > description
  
  vi config
  # add the following
  [gitweb]
     owner = Your Name

Pushing a git Repository to the Git Server

This needs to be done once to transfer your local repository to the git server.

Do the following from the root directory of your local git repository.

• git remote add origin user@git.softxs.ch:/home/git/gitroot/new-name.git
  git push origin master

Use of Branches

• TODO describe conventions for using branches

Application Services

Logging

1. Use Log4R

   • See: https://github.com/colbygk/log4r

   • Documentation: http://log4r.rubyforge.org

2. TODO define the using of log levels DEBUG < INFO < WARN < ERROR < FATAL

Configuring Logging

1. Add the following to Gemfile, and the run bundle install

   • gem 'log4r'

2. Add the following to config/application.rb. Add the line to the very end of the file

   • require File.expand_path(File.dirname(__FILE__) + "/log4r_init.rb")

3. Create the file config/log4r.yml with the following contents: log4r.yml

4. Create the file config/log4r_init.rb with the following contents: log4r_init.rb

Application Configuration

1. Use rails_config

   • See: https://github.com/railsjedi/rails_config

2. For more about Rails application configuration, in general terms:

   • http://guides.rubyonrails.org/configuring.html

Details:

1. YAML based configuration file
2. Can overrides/overlay configuration based on environment
3. Supports local configuration files to allow easy tweaking of installations and deviations from checked in configuration files
4. Supports embedded ruby in the yml file. For example:

   • filename : <%= "#{Rails.root}/log/#{Rails.env}.log" %>

5. Easy to access config variables. E.g. Settings.SXS.certsfile and/or Settings[‘’SXS’’][‘’certsfile”]
6. Supports nested configuration. This allows all application configuration to be pushed down under ‘’SXS” for instance to avoid conflicts with any other settings

HTML Templates

1. Use erb - Built into Ruby

Alternatives to investigate:

1. Haml

2. Slim

CSS Templates

1. TODO

Alternatives to investigate

1. CASS

2. SCSS

Database Server

1. Use MySQL - Preferably for all environments

Configuring MySQL

1. Add the following to your Gemfile

   • gem 'mysql2'
     gem 'bcrypt-ruby', '~> 3.0.0'
     gem 'therubyracer', :platforms => :ruby

2. Edit the config/database.yml file, and add configuration like the following for each environment:

   • development:
       adapter: mysql2
       encoding: utf8
       reconnect: true
       database: dbname
       pool: 5
       username: dbuser
       password: dbpasswd
       socket: /opt/local/var/run/mysql5/mysqld.sock

Notes:

1. In the Gemfile:
   1. The mysql2 Gem should be added at the top of the and be available for all environments
   2. The bcrypt-ruby and therubyracer Gems are probably already in the Gemfile and just need to be enabled
      1. The bcrypt-ruby Gem is needed for encrypting the MySQL password. If you get an error like the following then it may be rcaused by the Gem being missing

         #<Mysql2::Error: Access denied for user 'root'@'localhost' (using password: NO)>

      2. The therubyracer Gem is (apparently) needed by the mysql2 Gem. If you get a JavaScript related error, then it might be related to this

2. In the config/database.yml file
   1. Set the appropriate database name. Use different names for each environment

   2. Set the appropriate database user (TODO probably 'root'.. to be investigated) and password

   3. Note that 'rake db:reset' actually sets the database password for the db user, which may cause surprises
   4. If you get server timeouts, make sure 'reconnect' is set to true
3. You can create a new project that uses MySQL as the default database:

   • rails new project-name -d mysql

Authentication

1. Use Devise

   • See https://github.com/plataformatec/devise

2. Consider the following supporting modules:

   1. CanCan - Integrates with Devise and provides useful authentication functions that can be used in .erb templates

      • See: https://github.com/ryanb/cancan

      • See: http://www.tonyamoyal.com/2010/07/28/rails-authentication-with-devise-and-cancan-customizing-devise-controllers

   2. OmniAuth - Which probably supports logins via Google+, Facebook, etc.

      • See: https://github.com/intridea/omniauth

3. General discussion of Rails recurity

   • See: http://guides.rubyonrails.org/security.html

4. Other references:

   • http://www.dixis.com/?p=332

JavaScript Libraries

Ruby on Rails uses unobtrusive JavaScript, which makes use of custom HTML attributes for binding HTML elements to JavaScript functions. This is done via special parameters to server-side calls to, which means that the you don't need to have script= attributes in your HTML.

1. Use jQuery - For DOM manipulation

   • See: http://api.jquery.com

   • See: http://docs.jquery.com

   • It is included by default in Rails 3.2 (formerly Prototype was used by default)

2. Use Backbone.js - For managing client-side collections of records with REST synchronization to the server

   • See: http://backbonejs.org

   • See http://documentcloud.github.com/backbone/docs/backbone.html

   • See: https://github.com/documentcloud/backbone

3. Use Underscore.js - Contains many useful general purpose utility functions. Required by Backbone.js

   • See: http://underscorejs.org

Internationalization

1. Use I18n

   • See http://guides.rubyonrails.org/i18n.html

   • See section 11.20 in Hansson book

Automated Unit and Integration Testing

1. Use RSpec - A Ruby GEM for specifying unit and integration tests

   • See https://www.relishapp.com/rspec/rspec-rails/docs

2. Use FactoryGirl - For generating test data

   • See https://github.com/thoughtbot/factory_girl

3. Use: Faker - A Ruby GEM, for generating fake/sample test data

   • See http://faker.rubyforge.org/

4. Resources:

   • Hansson book, Chapter 18

   • http://pure-rspec-rubynation.herokuapp.com

5. RSpec test specifications should include the tracking system bug number (e.g. 'BUG-4765') in the test description. This allows the bug to be specifically tested for using the RSpec -e parameter. E.g. rspec spec -e 'BUG-4765'

Background Process (Event Daemon)

• TODO

• See Chapter 20 in Hansson book. Suggested alternatives:

  1. Delayed Job https://github.com/collectiveidea/delayed_job

  2. Resque https://github.com/defunkt/resque (Requires Redis, and key-value storage mechanism)

  3. Rails Runner
• See general discussion at

  • https://github.com/blog/542-introducing-resque

  • http://wrangl.com/djvsrq

  • http://www.dixis.com/?p=335

PDF File Generation

• TODO

Application Architecture

• TODO describe the division between MAPPS and V2

User Access Modeling

Definitions

1. Library - an entity that contains multiple Projects

   1. A Library is the repository that manages user login, e.g. it authenticates users, typically via user login name and password (or LDAP, etc.)
      1. Contains a catalog of user names, login names and authorization information, e.g. encrypted passwords or links to LDAP or other authentication external authentication systems
   2. A Library does not contain user role information for individual projects
      1. Except that it is able to provide a list of links that jump to the home pages of the projects (in the library) that the user has access to
      2. If a user doesn't have any roles for a particular project, then they do not even see that the project exists
         1. This might be managed by a configuration variable, to allow implementation of a compeny-based systems which let all users see the names of all projects

2. Project - an entity that contains user data, e.g. documents, revisions, tasks, etc.

   1. Each project must belong to exactly one library
   2. A project contains:
      1. Project metadata, stored in the project's database
         1. Including user access rights for all the project's users
      2. A set of files (revision files, correspondence files, ZIP files, etc.) stored in a directory tree
      3. The metadata database and files of a project are never mixed between projects. This is to:
         1. Ensure customer data privacy
         2. Make it possible to make individual project backups

Requirements

1. A user has the same login credentials for all projects, he has access to, within a single library
2. A library dictates the user authentication policy, e.g. how user logins are validated, for all the projects that belong to it
3. A library has a landing page
   1. The landing page is the user login page for the all projects that belong to it
4. A library has administrative transactions for defining and managing users

   1. There are library users that have library administrator roles

   2. The library configuration sets the login security policy, e.g. password length, frequency of password changes, etc.
      1. Initially this will be via configuration variables
      2. Later this might be managed by online transactions available to the library administrators
5. Integrity of project metadata:
   1. All metadata for a project is stored in a single database
   2. Databases never contain metadata from multiple projects
6. Projects can be migrated between libraries
   1. This will initially be done using a manual procedure, e.g. shell and SQL scripts
   2. Later this could be automated
7. User roles for individual projects are managed within the projects

8. There are users that have project administrator roles within projects

   1. A project administrator manages user roles for a project
   2. The project administrator role is limited the project it is associated with
   3. A user might have project administrator rights in multiple projects

9. User roles for library and project administration do not include the ability to grant the roles to others, which are controlled by seperate grant library administrator and grant project administrator roles