-
Notifications
You must be signed in to change notification settings - Fork 72
old style milia app tutorial
I'm leaving this tutorial here for historic reference purposes; but for most applications, you should rely on the generators to automatically set up devise and an integrated milia. If you ever wonder why something was done, however, this document should help answer your questions.
This tutorial is a capture of everything I did to create a sample app for milia. There's enough brief comments for anyone to follow step-by-step. It is based on my dev environment which is Ubuntu 13.10 on a PC. YMMV.
_This tutorial is based on milia version v1.0.0-beta-2 (latest is beta-2), so you _ probably should also reference the current doc/sample.sh (my running notes when testing the sample-milia-app) for any changes or latest info!
The "app" itself is merely a simple barebones structure to display an index page, require sign-in to do anything else, has a sign-up page for starting a new organization (ie tenant), a way to send invitations to other members, and a single tenanted model (members) to prove that tenanting is working.
you can see an exact copy of the sample on github: https://github.com/dsaronin/sample-milia-app
- doc/sample.sh -- will ALWAYS be the most recent of my notes for creating a sample app (for example in the edge branch: "newdev")
- github.com/milia/wiki/sample-milia-app-tutorial (this document) this should be the same as the sample.sh doc for the current stable release (or latest beta version); but markdown formatted https://github.com/dsaronin/milia/wiki/sample-milia-app-tutorial
- milia README:
- this will be the knowledgable programmer's digest of the essentials
- thus it won't cover some of the intricacies of actually implementing milia: either the tutorial or sample.sh will do that
- if you're a first time milia implementer, please use both the README and either of the two above documents for assistance: it will save you time.
If you run into difficulties while following the steps here, please be sure to reference the LINE NUMBER or SECTION of the point at which had a problem, as well as any output from that step.
if you've gone commando and have been making changes & enhancements OR have been trying to roll out a full app, you're more or less on your own. I strongly recommend experimenting with milia first in this simple format, get it working, then ADD in increasing layers of complexity and difficulty. Trying to make too many changes at once is a recipe for difficulty in troubleshooting. Don't expect to get rescued.
This file isn't fully executable as a shell script. There are just too many things you'll have to to do to help things along.
- Instructions for you to do things are in regular text; things you should type or cut&paste, will be in pre-formatted monospaced fonts. commands preceded by a "$" prompt indicate shell level command. commands preceded by a ">" prompt indicate some other program command. in either case, don't type the prompt as part of the command!
- I've bracketed groups of text to be edited/added to a file with the following style: things to do &/or edit or add things to add
- follow everything exactly in the order given
- there's non-milia related stuff, if you'll be using heroku to host; treat this as optional, if you'd like. but at least I know it works as a completed app.
This background is what I've done on my Ubuntu dev workstation so if you want to follow exactly, you'll need similar. None of this is necessarily required for milia; only to exactly bring up this sample-milia-app.
Make sure you have your ssh keys gen'd
$ ssh-keygen
Make sure you have some basic packages on your system
$ sudo apt-get install curl git vim vim-gnome
Make sure you've set up a github account, and git globals on your workstation.
Install RVM on your system. See http://rvm.io for more information and do any adjustments to your .bashrc, etc files as needed,
$ \curl -L https://get.rvm.io | bash -s stable
Make sure to install ruby 2.0.0
$ rvm install 2.0.0
I have all my projects in a directory called "projectspace", so these instructions start there.
$ mkdir projectspace
$ rvm gemset create projectspace
$ echo "projectspace" > projectspace/.ruby-gemset
$ echo "2.0.0" > projectspace/.ruby-version
$ cd projectspace
install rails (latest version)
$ gem install rails
- set up a heroku account at: http://heroku.com
- install heroku toolbelt: heroku, foreman
$ wget -qO- https://toolbelt.heroku.com/install-ubuntu.sh | sh
$ heroku login
set environment variable for later Procfile and later recaptcha usage; I put them in .bashrc.
export PORT=3000
export RACK_ENV=development
# OPTIONAL: recaptcha keys
export RECAPTCHA_PUBLIC_KEY=6LeYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKpT
export RECAPTCHA_PRIVATE_KEY=6LeBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBgQBv
@GITHUB: create a new repository <your-new-app> for <git-user> (you) anywhere below where you see sample-milia-app, change it to <your-new-app>.
$ cd projectspace # if not there already
$ rails new sample-milia-app
$ echo "sample" > sample-milia-app/.ruby-gemset
$ echo "2.0.0" > sample-milia-app/.ruby-version
$ echo "web: bundle exec thin start -R config.ru -p $PORT -e $RACK_ENV" > sample-milia-app/Procfile
$ rvm gemset create sample
$ cd sample-milia-app
$ git init
$ git add --all .
$ git commit -am 'initial commit'
$ git remote add origin [email protected]:<git-user>/sample-milia-app.git
$ git push -u origin master
I just copy my standard .gitignore from another project (as in sample below), but you can copy mine from sample-milia-app on github.
$ cp ../<somewhere else>/.gitignore .
$ vim Gemfile
First, comment OUT the turbolinks gem
# gem 'turbolinks'
then, enable rubyracer in Gemfile by de-commenting
gem 'therubyracer', platforms: :ruby
finally, ADD the following lines to Gemfile
ruby "2.0.0" # heroku likes this at the head, as line 2
# =========================================================
# sample-milia-app specific stuff
# =========================================================
# Bundle the extra gems:
gem 'haml-rails'
gem 'html2haml', :git => 'git://github.com/haml/html2haml.git' # "2.0.0.beta.2",
# stuff that heroku likes to have
gem 'thin'
gem "SystemTimer", :require => "system_timer", :platforms => :ruby_18
gem "rack-timeout"
gem 'rails_12factor'
# airbrake is optional and configured by config.use_airbrake in milia initializer
# default is false; if you change it to true, uncomment out the line below
# gem 'airbrake' # uncomment this if you will use airbrake for exception notifications
gem 'web-app-theme', :git => 'git://github.com/dsaronin/web-app-theme.git'
gem 'devise', '~>3.2'
gem 'milia', :git => 'git://github.com/dsaronin/milia.git', :branch => 'v1.0.0-beta-2'
# recaptcha is optional and configured by config.use_recaptcha in milia initializer
# default is true; if you change it to false, comment out the line below
gem 'recaptcha', :require => "recaptcha/rails"
comment out turbolinks in your Javascript manifest file; we won't need turbolinks for this simple sample.
// require turbolinks to
$ bundle install
Source for web-app-theme related notes and revisions: http://blog.bryanbibat.net/2011/09/24/starting-a-professional-rails-3-1-app-with-web-app-theme-devise-and-kaminari/
$ rails g controller home index
$ rm public/index.html
ADD the root :to => "home#index" within the do..end block
SampleMiliaApp::Application.routes.draw do
root :to => "home#index"
end
$ rake db:create
$ foreman start
http://localhost:3000/
you should see an empty template page for home/index
$ rails g web_app_theme:theme --engine=haml --theme="red" --app-name="Simple Milia App"
$ rm app/views/layouts/application.html.erb
$ rails g web_app_theme:themed home --themed-type=text --theme="red" --engine=haml
$ mv app/views/home/show.html.haml app/views/home/index.html.haml
$ rails g devise:install
$ rails g devise user
(of course, you will want to change your domain, email user_name and password to match your actual values!)
# devise says to define default url
config.action_mailer.default_url_options = { :host => 'localhost:3000' }
# set up for email sending even in dev mode
# Don't care if the mailer can't send
config.action_mailer.raise_delivery_errors = false
config.action_mailer.delivery_method = :smtp
ActionMailer::Base.smtp_settings = {
:address => "smtp.gmail.com",
:port => "587",
:authentication => :plain,
:user_name => "[email protected]",
:password => "my-password",
:enable_starttls_auto => true
}
this sample is showing as how it would be if your production server is hosted via heroku.com using the SENDGRID plugin for emailing.
# devise says to define default url
config.action_mailer.default_url_options = { :host => 'secure.simple-milia-app.com', :protocol => 'https' }
ActionMailer::Base.delivery_method = :smtp
ActionMailer::Base.smtp_settings = {
:address => 'smtp.sendgrid.net',
:port => '587',
:authentication => :plain,
:user_name => ENV['SENDGRID_USERNAME'],
:password => ENV['SENDGRID_PASSWORD'],
:domain => 'heroku.com'
}
# devise says to define default url
config.action_mailer.default_url_options = { :host => "www.example.com" }
add confirmable to line 4
devise :database_authenticatable, :registerable, :confirmable,
uncomment the confirmable section, it will then look as follows:
## Confirmable
t.string :confirmation_token
t.datetime :confirmed_at
t.datetime :confirmation_sent_at
t.string :unconfirmed_email # Only if using reconfirmable
and uncomment the confirmation_token index line
add_index :users, :confirmation_token, :unique => true
change mailer_sender to be your from: email address
config.mailer_sender = "[email protected]"
OPTIONAL: locate and uncomment the following lines (in various places):
config.pepper = '46f2....'
config.confirmation_keys = [ :email ]
config.email_regexp = /\A[^@]+@[^@]+\z/
$ rake db:migrate
stop/restart foreman: ^c stops foreman; foreman start restarts it; F5 refreshes the browser page
$ rails g web_app_theme:theme sign --layout-type=sign --theme="red" --engine=haml --app-name="Simple Milia App"
NOTE: please see details and cautions at: http://guides.rubyonrails.org/asset_pipeline.html Section 4.1 Precompiling Assets
config.time_zone = 'Pacific Time (US & Canada)'
# For faster asset precompiles, you can partially load your application.
# In that case, templates cannot see application objects or methods.
# Heroku requires this to be false.
config.assets.initialize_on_precompile = false
by adding the following into the class .... end block
config.to_prepare do
Devise::SessionsController.layout "sign"
Devise::RegistrationsController.layout "sign"
Devise::ConfirmationsController.layout "sign"
Devise::PasswordsController.layout "sign"
end
if we use devise to gen the views, they'll be genned in erb and a different format from the layout style we're using. my web_app_theme has a generator to gen them automagically
$ rails g web_app_theme:devise
NOTE: this line is only for the basic devise (no milia) version; we will later uncomment or remove this line when we install milia
before_action :authenticate_user!
skip_before_action :authenticate_user!, :only => [ :index ]
NOTE: we will later DELETE all users added in this manner BEFORE we install milia. Reason is because currently there is no tenanting. DO NOT TRY TO LATER MANUALLY ATTEMPT TO CONVERT THESE INITIAL USERS TO A TENANTING MODEL: it is poor software practice to do that. you need to be testing and verifying that we've got devise up and enabled by using the devise-based sign up, confirm, sign in process.
- sign up as a new user,
- the log file will show that an email was sent together with the activation code & URL and if your email/password are correct, an email should have been sent as well!
- copy & paste this address as-is into the browser address area & go to it to activate
- it will take you to a sign in screen; sign in
- REFRESH index page (to refresh the logout validity token)
- sign out
- sign in again as the user
$ rail c
> User.all.each{|x| x.destroy}
> exit
$ rake db:rollback
gem 'activerecord-session_store', github: 'rails/activerecord-session_store'
$ bundle install
$ rails g active_record:session_migration
# milia member_invitable
t.boolean :skip_confirm_change_password, :default => false
t.references :tenant
$ rails g model tenant tenant:references name:string:index
$ rails g migration CreateTenantsUsersJoinTable tenants users
then uncomment the first index line as follows:
t.index [:tenant_id, :user_id]
NOTE: before all tenanted controllers, you MUST HAVE a
before_action :authenticate_tenant!
It is best to have it at the start of your application_controller If you happen to have any general universal access controllers, then you can place at the top of those specific controllers:
skip_before_action :authenticate_tenant!, :only => [ <action name> ]
(make it look like the statement below)
before_action :authenticate_tenant! # authenticates user and sets up tenant
rescue_from ::Milia::Control::MaxTenantExceeded, :with => :max_tenants
rescue_from ::Milia::Control::InvalidTenantAccess, :with => :invalid_tenant
# milia defines a default max_tenants, invalid_tenant exception handling
# but you can override if you wish to handle directly
as :user do # *MUST* come *BEFORE* devise's definitions (below)
match '/user/confirmation' => 'milia/confirmations#update', :via => :put, :as => :update_user_confirmation
end
devise_for :users, :controllers => {
:registrations => "milia/registrations",
:confirmations => "milia/confirmations",
:sessions => "milia/sessions",
:passwords => "milia/passwords",
}
acts_as_universal_and_determines_account
belongs_to :tenant
acts_as_universal_and_determines_tenant
def self.create_new_tenant(tenant_params, coupon_params)
tenant = Tenant.new(:name => tenant_params[:name])
if new_signups_not_permitted?(coupon_params)
raise ::Milia::Control::MaxTenantExceeded, "Sorry, new accounts not permitted at this time"
else
tenant.save # create the tenant
end
return tenant
end
# ------------------------------------------------------------------------
# new_signups_not_permitted? -- returns true if no further signups allowed
# args: params from user input; might contain a special 'coupon' code
# used to determine whether or not to allow another signup
# ------------------------------------------------------------------------
def self.new_signups_not_permitted?(params)
return false
end
# ------------------------------------------------------------------------
# tenant_signup -- setup a new tenant in the system
# CALLBACK from devise RegistrationsController (milia override)
# AFTER user creation and current_tenant established
# args:
# user -- new user obj
# tenant -- new tenant obj
# other -- any other parameter string from initial request
# ------------------------------------------------------------------------
def self.tenant_signup(user, tenant, other = nil)
# StartupJob.queue_startup( tenant, user, other )
# any special seeding required for a new organizational tenant
end
skip_before_action :authenticate_tenant!, :only => [ :index ]
this will give you improved handling for letting user know what is expected. If you want to have a welcome page for signed in users, uncomment the redirect_to line, etc.
def index
if user_signed_in?
# was there a previous error msg carry over? make sure it shows in flasher
flash[:notice] = flash[:error] unless flash[:error].blank?
# redirect_to( welcome_path() )
else
if flash[:notice].blank?
flash[:notice] = "sign in if your organization has an account"
end
end # if logged in .. else first time
end
$ rake db:migrate
To do that, copy doc/milia-initializer.rb to config/initializers/milia.rb
NOTE: if Milia.use_coupon is true (default configuration option), then your sign up form MUST return a parameter
:coupon => { :coupon => <string> }
which can also be blank.
default behavior for handling strong_parameters in Rails see: https://github.com/rails/strong_parameters#handling-of-unpermitted-keys choose one of the two options: :raise OR :log
ActionController::Parameters.action_on_unpermitted_parameters = :raise | :log
http://localhost:3000/
- click sign up to sign up a new account
- get confirmation email (or view in log)
- activate the new account, sign in, sign out, etc.
Using the rails console:
$ rails c
> User.all.each{|x| x.destroy}
> Tenant.all.each{|x| x.destroy}
> exit
$ rails g resource member tenant:references user:references first_name:string last_name:string
has_many :members, dependent: :destroy
# ------------------------------------------------------------------------
def self.tenant_signup(user, tenant, other = nil)
# StartupJob.queue_startup( tenant, user, other )
# any special seeding required for a new organizational tenant
Member.create_org_admin(user)
end
has_one :member, :dependent => :destroy
acts_as_tenant
DEFAULT_ADMIN = {
first_name: "Admin",
last_name: "Please edit me",
favorite_color: "blue"
}
def self.create_new_member(user, params)
# add any other initialization for a new member
return user.create_member( params )
end
def self.create_org_admin(user)
new_member = create_new_member(user, DEFAULT_ADMIN)
unless new_member.errors.empty?
raise ArgumentError, new_member.errors.full_messages.uniq.join(", ")
end
return new_member
end%h1 Simple Milia App
.block#block-signup
%h2 Invite a new member into #{@org_name}
.content.login
.flash
- flash.each do |type, message|
%div{ :class => "message #{type}" }
%p= message
- flash.clear # clear contents so we won't see it again
= form_for(@member, :html => { :class => "form login" }) do |f|
- unless @member.errors.empty? && @user.errors.empty?
#errorExplanation.group
%ul
= @member.errors.full_messages.uniq.inject(''){|str, msg| (str << "<li> #{msg}") }.html_safe
= @user.errors.full_messages.uniq.inject(''){|str, msg| (str << "<li> #{msg}") }.html_safe
= fields_for( :user ) do |w|
.group
= w.label :email, :class => "label "
= w.text_field :email, :class => "text_field"
%span.description Ex. test@example.com; must be unique
.group
= f.label :first_name, :class => "label "
= f.text_field :first_name, :class => "text_field"
.group
= f.label :last_name, :class => "label "
= f.text_field :last_name, :class => "text_field"
.group
= f.label :favorite_color, :class => "label "
= f.text_field :favorite_color, :class => "text_field"
%span.description What is your favorite color?
.group.navform.wat-cf
%button.button{ :type => "submit" }
= image_tag "web-app-theme/icons/key.png"
Create user and invite before_action :prep_org_name
private
# org_name will be passed to layout & view
def prep_org_name()
@org_name = ( user_signed_in? ?
Tenant.current_tenant.name :
"Simple Milia App"
)
endThe following is not a requirement, but serves to show how to handle tenanted sign ins and welcome pages replaces the two instances of "Simple Milia App" with (everything between the quotes but not including the quotes): "= @org_name", make the results look like the two lines below
%title= @org_name
= link_to @org_name, "/"
with the "sign_up" link to look like the following:
%li
- if user_signed_in?
= link_to t("web-app-theme.invite", :default => "Invite member"), new_member_path
- else
= link_to( t("web-app-theme.signup", :default => "Sign up"), new_user_registration_path ) layout "sign", :only => [:new, :edit, :create]
def new()
@member = Member.new()
@user = User.new()
end
def create()
@user = User.new( user_params )
# ok to create user, member
if @user.save_and_invite_member() && @user.create_member( member_params )
flash[:notice] = "New member added and invitation email sent to #{@user.email}."
redirect_to root_path
else
flash[:error] = "errors occurred!"
@member = Member.new( member_params ) # only used if need to revisit form
render :new
end
end
private
def member_params()
params.require(:member).permit(:first_name, :last_name, :favorite_color)
end
def user_params()
params.require(:user).permit(:email, :password, :password_confirmation)
end$ rake db:migrate
- you will have to first sign-up, confirm, then you can invite_member
- sign-out, confirm new member, etc