Merge pull request #507 from shingara/features/improve_documentation_about_variable

[WIP] Features/improve documentation about env variable

Merge pull request #507 from shingara/features/improve_documentation_about_variable
[WIP] Features/improve documentation about env variable
Cyril Mougel
2 parents 4e0d8fd4 ad951867
Showing 7 changed files with 117 additions and 18 deletions Show diff stats
Gemfile
README.md
config/initializers/_load_config.rb
config/initializers/mongo.rb
config/initializers/ssl_enforcer.rb
docs/ENV-VARIABLES.md
spec/models/problem_spec.rb
@@ -17,7 +17,7 @@ gem &#39;strong_parameters&#39;
 gem 'SystemTimer', :platform => :ruby_18
 gem 'actionmailer_inline_css'
 gem 'kaminari', '>= 0.14.1'
-gem 'rack-ssl-enforcer'
+gem 'rack-ssl-enforcer', :require => false
 # fabrication 1.3.0 is last supporting ruby 1.8. Update when stop supporting this version too
 gem 'fabrication', "~> 1.3.0"   # Used for both tests and demo data
 gem 'rails_autolink'
@@ -149,7 +149,7 @@ cap deploy:setup deploy
 git clone http://github.com/errbit/errbit.git
 ```
   * Update `db/seeds.rb` with admin credentials for your initial login.
-  
+
   * Run `bundle`
  
   * Create & configure for Heroku
@@ -469,7 +469,11 @@ Solutions known to work are listed below:
 Develop on Errbit
 -----------------
  
-A guide can help on this way on  [**Errbit Advanced Developer Guide**](https://github.com/errbit/errbit/blob/master/docs/DEVELOPER-ADVANCED.md)
+A guide can help on this way on  [**Errbit Advanced Developer Guide**](docs/DEVELOPER-ADVANCED.md)
+
+## Other documentation
+
+* [All ENV variables availables to configure Errbit](docs/ENV-VARIABLES.md)
  
 TODO
 ----
@@ -4,15 +4,17 @@ default_config_file = Rails.root.join(&quot;config&quot;, &quot;config.example.yml&quot;)
 # Allow a Rails Engine to override config by defining it earlier
 unless defined?(Errbit::Config)
   Errbit::Config = OpenStruct.new
+  use_env = ENV['HEROKU'] || ENV['USE_ENV']
  
   # If Errbit is running on Heroku, config can be set from environment variables.
-  if ENV['HEROKU']
+  if use_env
     Errbit::Config.host = ENV['ERRBIT_HOST']
     Errbit::Config.email_from = ENV['ERRBIT_EMAIL_FROM']
-    Errbit::Config.email_at_notices = ENV['ERRBIT_EMAIL_AT_NOTICES']
-    Errbit::Config.confirm_resolve_err = ENV['ERRBIT_CONFIRM_RESOLVE_ERR']
-    Errbit::Config.user_has_username = ENV['ERRBIT_USER_HAS_USERNAME']
-    Errbit::Config.allow_comments_with_issue_tracker = ENV['ERRBIT_ALLOW_COMMENTS_WITH_ISSUE_TRACKER']
+    #  Not really easy to use like an env because need an array and ENV return a string :(
+    # Errbit::Config.email_at_notices = ENV['ERRBIT_EMAIL_AT_NOTICES']
+    Errbit::Config.confirm_resolve_err = ENV['ERRBIT_CONFIRM_RESOLVE_ERR'].to_i == 0
+    Errbit::Config.user_has_username = ENV['ERRBIT_USER_HAS_USERNAME'].to_i == 1
+    Errbit::Config.allow_comments_with_issue_tracker = ENV['ERRBIT_ALLOW_COMMENTS_WITH_ISSUE_TRACKER'].to_i == 0
     Errbit::Config.enforce_ssl = ENV['ERRBIT_ENFORCE_SSL']
  
     Errbit::Config.use_gravatar = ENV['ERRBIT_USE_GRAVATAR']
@@ -29,7 +31,7 @@ unless defined?(Errbit::Config)
       :authentication => :plain,
       :user_name      => ENV['SMTP_USERNAME']   || ENV['SENDGRID_USERNAME'],
       :password       => ENV['SMTP_PASSWORD']   || ENV['SENDGRID_PASSWORD'],
-      :domain         => ENV['SENDGRID_DOMAIN'] || ENV['ERRBIT_EMAIL_FROM'].split('@').last
+      :domain         => ENV['SMTP_DOMAIN'] || ENV['SENDGRID_DOMAIN'] || ENV['ERRBIT_EMAIL_FROM'].split('@').last
     }
   end
  
@@ -44,7 +46,7 @@ unless defined?(Errbit::Config)
       Errbit::Config.send("#{k}=", v)
     end
   # Show message if we are not running tests, not running on Heroku, and config.yml doesn't exist.
-  elsif not ENV['HEROKU']
+  elsif not use_env
     puts "Please copy 'config/config.example.yml' to 'config/config.yml' and configure your settings. Using default settings."
   end
  
@@ -76,4 +78,4 @@ end
  
 if Rails.env.production?
   Rails.application.config.consider_all_requests_local = Errbit::Config.display_internal_errors
-end
 \ No newline at end of file
+end
-if mongo = ENV['MONGOLAB_URI'] || ENV['MONGOHQ_URL']
-  settings = URI.parse(mongo)
-  database_name = settings.path.gsub(/^\//, '')
+# Some code extract from Mongoid gem
+config_file = Rails.root.join("config", "mongoid.yml")
+if config_file.file? &&
+  YAML.load(ERB.new(File.read(config_file)).result)[Rails.env].values.flatten.any?
+  ::Mongoid.load!(config_file)
+else
+  # No mongoid.yml file. Use ENV variable to define your MongoDB
+  # configuration
+  if mongo = ENV['MONGOLAB_URI'] || ENV['MONGOHQ_URL']
+    settings = URI.parse(mongo)
+    database_name = settings.path.gsub(/^\//, '')
+  else
+    settings = OpenStruct.new({
+      :host => ENV['MONGOID_HOST'],
+      :port => ENV['MONGOID_PORT'],
+      :user => ENV['MONGOID_USERNAME'],
+      :password => ENV['MONGOID_PASSWORD']
+    })
+    database_name = ENV['MONGOID_DATABASE']
+  end
  
   Mongoid.configure do |config|
-    config.master = Mongo::Connection.new(settings.host, settings.port).db(database_name)
+    config.master = Mongo::Connection.new(
+      settings.host,
+      settings.port
+    ).db(database_name)
     config.master.authenticate(settings.user, settings.password) if settings.user
-    config.allow_dynamic_fields = false
-    config.use_activesupport_time_zone = true
   end
 end
  
+Mongoid.allow_dynamic_fields = false
+Mongoid.use_activesupport_time_zone = true
+Mongoid.identity_map_enabled = true
 # Enforce SSL connections, if configured
 if Errbit::Config.enforce_ssl
+  require 'rack/ssl-enforcer'
   ActionMailer::Base.default_url_options.merge!(:protocol => 'https://')
   Errbit::Application.configure do
     config.middleware.use Rack::SslEnforcer, :except => /^\/deploys/
@@ -0,0 +1,71 @@
+# Which env variable you can use ?
+
+Errbit can be almost configured by some ENVIRONMENT variables. If you
+use this variable, you don't need copy all of you configuration file
+
+To activate this env variable you need activate it by a Variable env.
+You can do that with HEROKU or USE_ENV variable
+
+If you activate it you can use all of this env variable :
+
+## Errbit base configuration
+
+* ERRBIT_HOST : the host of your errbit instance (not define by default)
+* ERRBIT_EMAIL_FROM : the email sending all of your notification (not
+  define by default )
+* ERRBIT_CONFIRM_RESOLVE_ERR : define if you need confirm when you mark
+  a problem resolve. ( true by default, fill it and you not need
+confirm )
+* ERRBIT_USER_HAS_USERNAME : allow identify your user by username
+  instead of email. ( false by default, set to '1' to activate it)
+* ERRBIT_ALLOW_COMMENTS_WITH_ISSUE_TRACKER : define if you activate the
+  comment or not. By default comment are
+* ERRBIT_ENFORCE_SSL : allow force the ssl on all the application. By
+  default is false
+* ERRBIT_USE_GRAVATAR : allow use gravatar to see user gravatar in user
+  comment and page
+
+## Authentification configuration
+
+Environement variable allow define how you can auth on your errbit
+
+### Github authentification
+
+You can allow the GITHUB auth
+
+* GITHUB_AUTHENTIFICATION : define if you allow the github auth. By
+  default false
+* GITHUB_CLIENT_ID : you github app client id to use in your github auth
+* GITHUB_SECRET : your github app secret to use in your github auth
+* GITHUB_ACCESS_SCOPE : The scope to ask to access on github account
+
+## Email sending configuration
+
+You can define how you connect your email sending system By all of this
+information. All mail can be send only by SMTP if you use variable
+system
+
+* SMTP_SERVER
+* SMTP_PORT
+* SMTP_USERNAME
+* SMTP_PASSWORD
+* SMTP_DOMAIN
+
+## MongoDB
+
+You can define your MongoDB connection by 2 ways. If you have an URL,
+you can define one of this ENV variables. All independently can works
+
+* MONGOLAB_URI
+* MONGOHQ_URL
+
+If you have a complete MongoDB connection you can define it by all
+information associate to your MongoDB connection. You need define all
+variable.
+
+* MONGOID_HOST
+* MONGOID_PORT
+* MONGOID_USERNAME
+* MONGOID_PASSWORD
+* MONGOID_DATABASE
+
@@ -104,7 +104,7 @@ describe Problem do
  
     it "should record the time when it was resolved" do
       problem = Fabricate(:problem)
-      expected_resolved_at = Time.now
+      expected_resolved_at = Time.zone.now
       Timecop.freeze(expected_resolved_at) do
         problem.resolve!
       end
...	...	@@ -17,7 +17,7 @@ gem 'strong_parameters'
17	17	gem 'SystemTimer', :platform => :ruby_18
18	18	gem 'actionmailer_inline_css'
19	19	gem 'kaminari', '>= 0.14.1'
20		-gem 'rack-ssl-enforcer'
	20	+gem 'rack-ssl-enforcer', :require => false
21	21	# fabrication 1.3.0 is last supporting ruby 1.8. Update when stop supporting this version too
22	22	gem 'fabrication', "~> 1.3.0" # Used for both tests and demo data
23	23	gem 'rails_autolink'
...	...
...	...	@@ -149,7 +149,7 @@ cap deploy:setup deploy
149	149	git clone http://github.com/errbit/errbit.git
150	150	```
151	151	* Update `db/seeds.rb` with admin credentials for your initial login.
152		-
	152	+
153	153	* Run `bundle`
154	154
155	155	* Create & configure for Heroku
...	...	@@ -469,7 +469,11 @@ Solutions known to work are listed below:
469	469	Develop on Errbit
470	470	-----------------
471	471
472		-A guide can help on this way on [Errbit Advanced Developer Guide](https://github.com/errbit/errbit/blob/master/docs/DEVELOPER-ADVANCED.md)
	472	+A guide can help on this way on [Errbit Advanced Developer Guide](docs/DEVELOPER-ADVANCED.md)
	473	+
	474	+## Other documentation
	475	+
	476	+* [All ENV variables availables to configure Errbit](docs/ENV-VARIABLES.md)
473	477
474	478	TODO
475	479	----
...	...
...	...	@@ -4,15 +4,17 @@ default_config_file = Rails.root.join("config", "config.example.yml")
4	4	# Allow a Rails Engine to override config by defining it earlier
5	5	unless defined?(Errbit::Config)
6	6	Errbit::Config = OpenStruct.new
	7	+ use_env = ENV['HEROKU'] \|\| ENV['USE_ENV']
7	8
8	9	# If Errbit is running on Heroku, config can be set from environment variables.
9		- if ENV['HEROKU']
	10	+ if use_env
10	11	Errbit::Config.host = ENV['ERRBIT_HOST']
11	12	Errbit::Config.email_from = ENV['ERRBIT_EMAIL_FROM']
12		- Errbit::Config.email_at_notices = ENV['ERRBIT_EMAIL_AT_NOTICES']
13		- Errbit::Config.confirm_resolve_err = ENV['ERRBIT_CONFIRM_RESOLVE_ERR']
14		- Errbit::Config.user_has_username = ENV['ERRBIT_USER_HAS_USERNAME']
15		- Errbit::Config.allow_comments_with_issue_tracker = ENV['ERRBIT_ALLOW_COMMENTS_WITH_ISSUE_TRACKER']
	13	+ # Not really easy to use like an env because need an array and ENV return a string :(
	14	+ # Errbit::Config.email_at_notices = ENV['ERRBIT_EMAIL_AT_NOTICES']
	15	+ Errbit::Config.confirm_resolve_err = ENV['ERRBIT_CONFIRM_RESOLVE_ERR'].to_i == 0
	16	+ Errbit::Config.user_has_username = ENV['ERRBIT_USER_HAS_USERNAME'].to_i == 1
	17	+ Errbit::Config.allow_comments_with_issue_tracker = ENV['ERRBIT_ALLOW_COMMENTS_WITH_ISSUE_TRACKER'].to_i == 0
16	18	Errbit::Config.enforce_ssl = ENV['ERRBIT_ENFORCE_SSL']
17	19
18	20	Errbit::Config.use_gravatar = ENV['ERRBIT_USE_GRAVATAR']
...	...	@@ -29,7 +31,7 @@ unless defined?(Errbit::Config)
29	31	:authentication => :plain,
30	32	:user_name => ENV['SMTP_USERNAME'] \|\| ENV['SENDGRID_USERNAME'],
31	33	:password => ENV['SMTP_PASSWORD'] \|\| ENV['SENDGRID_PASSWORD'],
32		- :domain => ENV['SENDGRID_DOMAIN'] \|\| ENV['ERRBIT_EMAIL_FROM'].split('@').last
	34	+ :domain => ENV['SMTP_DOMAIN'] \|\| ENV['SENDGRID_DOMAIN'] \|\| ENV['ERRBIT_EMAIL_FROM'].split('@').last
33	35	}
34	36	end
35	37
...	...	@@ -44,7 +46,7 @@ unless defined?(Errbit::Config)
44	46	Errbit::Config.send("#{k}=", v)
45	47	end
46	48	# Show message if we are not running tests, not running on Heroku, and config.yml doesn't exist.
47		- elsif not ENV['HEROKU']
	49	+ elsif not use_env
48	50	puts "Please copy 'config/config.example.yml' to 'config/config.yml' and configure your settings. Using default settings."
49	51	end
50	52
...	...	@@ -76,4 +78,4 @@ end
76	78
77	79	if Rails.env.production?
78	80	Rails.application.config.consider_all_requests_local = Errbit::Config.display_internal_errors
79		-end
80	81	\ No newline at end of file
	82	+end
...	...
1		-if mongo = ENV['MONGOLAB_URI'] \|\| ENV['MONGOHQ_URL']
2		- settings = URI.parse(mongo)
3		- database_name = settings.path.gsub(/^\//, '')
	1	+# Some code extract from Mongoid gem
	2	+config_file = Rails.root.join("config", "mongoid.yml")
	3	+if config_file.file? &&
	4	+ YAML.load(ERB.new(File.read(config_file)).result)[Rails.env].values.flatten.any?
	5	+ ::Mongoid.load!(config_file)
	6	+else
	7	+ # No mongoid.yml file. Use ENV variable to define your MongoDB
	8	+ # configuration
	9	+ if mongo = ENV['MONGOLAB_URI'] \|\| ENV['MONGOHQ_URL']
	10	+ settings = URI.parse(mongo)
	11	+ database_name = settings.path.gsub(/^\//, '')
	12	+ else
	13	+ settings = OpenStruct.new({
	14	+ :host => ENV['MONGOID_HOST'],
	15	+ :port => ENV['MONGOID_PORT'],
	16	+ :user => ENV['MONGOID_USERNAME'],
	17	+ :password => ENV['MONGOID_PASSWORD']
	18	+ })
	19	+ database_name = ENV['MONGOID_DATABASE']
	20	+ end
4	21
5	22	Mongoid.configure do \|config\|
6		- config.master = Mongo::Connection.new(settings.host, settings.port).db(database_name)
	23	+ config.master = Mongo::Connection.new(
	24	+ settings.host,
	25	+ settings.port
	26	+ ).db(database_name)
7	27	config.master.authenticate(settings.user, settings.password) if settings.user
8		- config.allow_dynamic_fields = false
9		- config.use_activesupport_time_zone = true
10	28	end
11	29	end
12	30
	31	+Mongoid.allow_dynamic_fields = false
	32	+Mongoid.use_activesupport_time_zone = true
	33	+Mongoid.identity_map_enabled = true
...	...
1	1	# Enforce SSL connections, if configured
2	2	if Errbit::Config.enforce_ssl
	3	+ require 'rack/ssl-enforcer'
3	4	ActionMailer::Base.default_url_options.merge!(:protocol => 'https://')
4	5	Errbit::Application.configure do
5	6	config.middleware.use Rack::SslEnforcer, :except => /^\/deploys/
...	...
...	...	@@ -0,0 +1,71 @@
	1	+# Which env variable you can use ?
	2	+
	3	+Errbit can be almost configured by some ENVIRONMENT variables. If you
	4	+use this variable, you don't need copy all of you configuration file
	5	+
	6	+To activate this env variable you need activate it by a Variable env.
	7	+You can do that with HEROKU or USE_ENV variable
	8	+
	9	+If you activate it you can use all of this env variable :
	10	+
	11	+## Errbit base configuration
	12	+
	13	+* ERRBIT_HOST : the host of your errbit instance (not define by default)
	14	+* ERRBIT_EMAIL_FROM : the email sending all of your notification (not
	15	+ define by default )
	16	+* ERRBIT_CONFIRM_RESOLVE_ERR : define if you need confirm when you mark
	17	+ a problem resolve. ( true by default, fill it and you not need
	18	+confirm )
	19	+* ERRBIT_USER_HAS_USERNAME : allow identify your user by username
	20	+ instead of email. ( false by default, set to '1' to activate it)
	21	+* ERRBIT_ALLOW_COMMENTS_WITH_ISSUE_TRACKER : define if you activate the
	22	+ comment or not. By default comment are
	23	+* ERRBIT_ENFORCE_SSL : allow force the ssl on all the application. By
	24	+ default is false
	25	+* ERRBIT_USE_GRAVATAR : allow use gravatar to see user gravatar in user
	26	+ comment and page
	27	+
	28	+## Authentification configuration
	29	+
	30	+Environement variable allow define how you can auth on your errbit
	31	+
	32	+### Github authentification
	33	+
	34	+You can allow the GITHUB auth
	35	+
	36	+* GITHUB_AUTHENTIFICATION : define if you allow the github auth. By
	37	+ default false
	38	+* GITHUB_CLIENT_ID : you github app client id to use in your github auth
	39	+* GITHUB_SECRET : your github app secret to use in your github auth
	40	+* GITHUB_ACCESS_SCOPE : The scope to ask to access on github account
	41	+
	42	+## Email sending configuration
	43	+
	44	+You can define how you connect your email sending system By all of this
	45	+information. All mail can be send only by SMTP if you use variable
	46	+system
	47	+
	48	+* SMTP_SERVER
	49	+* SMTP_PORT
	50	+* SMTP_USERNAME
	51	+* SMTP_PASSWORD
	52	+* SMTP_DOMAIN
	53	+
	54	+## MongoDB
	55	+
	56	+You can define your MongoDB connection by 2 ways. If you have an URL,
	57	+you can define one of this ENV variables. All independently can works
	58	+
	59	+* MONGOLAB_URI
	60	+* MONGOHQ_URL
	61	+
	62	+If you have a complete MongoDB connection you can define it by all
	63	+information associate to your MongoDB connection. You need define all
	64	+variable.
	65	+
	66	+* MONGOID_HOST
	67	+* MONGOID_PORT
	68	+* MONGOID_USERNAME
	69	+* MONGOID_PASSWORD
	70	+* MONGOID_DATABASE
	71	+
...	...
...	...	@@ -104,7 +104,7 @@ describe Problem do
104	104
105	105	it "should record the time when it was resolved" do
106	106	problem = Fabricate(:problem)
107		- expected_resolved_at = Time.now
	107	+ expected_resolved_at = Time.zone.now
108	108	Timecop.freeze(expected_resolved_at) do
109	109	problem.resolve!
110	110	end
...	...