mno-enterprise 3.1.4 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 21b1e4d08bc55b05407698087f4e8ab2105f475d
-  data.tar.gz: 5fba159f9629501b7c64476d0453ab3d1b19bb50
+  metadata.gz: a76a9fadf68efdbeb9c468da460896200e5b0acb
+  data.tar.gz: c04a6a7193b25262f072be83c18ff13e26773581
 SHA512:
-  metadata.gz: 69369c1df07e7aced1920bf97bbbf5db656eb5becb1efadd107364c68b611794c455d2b094faf231eb20e850c7ecc694daf1be663d683d9803cf119ba0249eb6
-  data.tar.gz: c24118bfd9ee2324966842908375f0f0e5006024a9da0929d90906a247acead174818814ab4bbe2f04167db73be95abc93118d480ba7cc72e3ca3e9a34d099ab
+  metadata.gz: 845f7e3c5ec67837e9a5e5d9bda16b722617c3ba89d82cf3c6bdc1f6dbcb8406a95c19e345e81e09c82ccde35759c9403ab3a30f3787492042e8ed9dbb1213d7
+  data.tar.gz: 3f87243eb41add2d9cd6252804988d3da9fb995226abda38866ccef9c5e6d0a0264f781f9a7aef3ccf133cbb69064eac426807aa73a8a91c005fbae6c04c5ccd

data/README.md

@@ -17,17 +17,24 @@ The goal of this engine is to provide a base that you can easily extend with cus
 - - -
 
 1.  [Install](#install)
-2.  [Configuration](#configuration)
-3.  [Building the Frontend](#building-the-frontend)
-4.  [Modifying the style - Theme Previewer](#modifying-the-style---theme-previewer)
-5.  [Extending the Frontend](#extending-the-frontend)
-6.  [Replacing the Frontend](#replacing-the-frontend)
-7.  [Generating a database extension](#generating-a-database-extension)
-8.  [Deploying](#deploying)
+2.  [Upgrade](#upgrade)
+3.  [Configuration](#configuration)
+    1. [Emailing Platform](#emailing-platform)
+    2. [Intercom](#intercom)
+    3. [Active Job Backend](#active-job-backend)
+4.  [Building the Frontend](#building-the-frontend)
+5.  [Modifying the style - Theme Previewer](#modifying-the-style---theme-previewer)
+6.  [Extending the Frontend](#extending-the-frontend)
+    1. [Adding a custom font](#adding-a-custom-font)
+    2. [Adding a favicon](#adding-favicon)
+7.  [Replacing the Frontend](#replacing-the-frontend)
+8.  [Extending the Backend](#extending-the-backend)
+    1. [Overriding Models and Controllers with the Decorator Pattern](#overriding-models-and-controllers-with-the-decorator-pattern)
+    2. [Generating a database extension](#generating-a-database-extension)
+9.  [Deploying](#deploying)
     1.  [Deploy a Puma stack on EC2 via Webistrano/Capistrano](#deploy-a-puma-stack-on-ec2-via-webistranocapistrano)
     2.  [Sample nginx config for I18n](#sample-nginx-config-for-i18n)
     3.  [Health Checks](#health-checks)
-9.  [Migrating from v2 to v3](#migrating-from-v2-to-v3)
 10. [Contributing](#contributing)
 
 - - -
@@ -68,22 +75,29 @@ The install script will perform three things:
 - Create a /frontend directory in your application for all frontend customisations/overrides
 
 **Manual Node setup (optional):**
-Building the frontend requires you to have nodejs and gulp install. While the rake task will attempt to install these dependencies, you may want to install these manually prior to running the install task. See the [nodejs website](https://nodejs.org/en/) for intructions on how to install node on your machine.
+Building the frontend requires you to have nodejs and yarn installed. While the rake task will attempt to install these dependencies, you may want to install these manually prior to running the install task.
+See the [nodejs](https://nodejs.org/en/) and [yarn](https://yarnpkg.com/en/docs/install) websites for instructions on how install them on your machine.
 
 Once node is installed, you can run the following commands to ensure that all dependencies are installed:
 ```bash
 bin/rake mnoe:frontend:install_dependencies
 ```
 
+## Upgrade
+
+We follow [Semantic Versioning](https://semver.org/) so upgrading to a compatible version should be straightforward.
+
+For major upgrade between versions see [UPGRADING](UPGRADING.md).
+
 ## Configuration
 
 ### Emailing platform
 
-Maestrano Enterprise support either [Mandrill](https://www.mandrill.com/) or [SparkPost](https://www.sparkpost.com/).
+Maestrano Enterprise supports either [Mandrill](https://www.mandrill.com/) or [SparkPost](https://www.sparkpost.com/) as well as regular SMTP.
 
-You can use either provider as long as your account has the [required templates](https://maestrano.atlassian.net/wiki/display/MNOE/Emailing).
+You can use either provider as long as your account has the [required templates](https://maestrano.atlassian.net/wiki/display/DEV/Emailing).
 
-If you  want to copy the default templates to your own account you can use the tools in `tools/emails`
+If you  want to copy the default templates to your own account you can use the tools in `tools/emails`.
 
 #### Mandrill
 
@@ -116,24 +130,22 @@ end
 ```
 
 #### SMTP
-SMTP server settings are needed to send emails via SMTP. In case there's no SMTP server, a personal gmail account could be used as an alternative.
-To use gmail to send SMTP emails, the gmail account should be set to allow "less secure apps".
-Typically for security reasons, system environment variables 'SMTP_USERNAME' and 'SMTP_PASSWORD' should be used to set the SMTP credentials.
+
+It's also possible to use a regular SMTP server. In this case, Maestrano Enterprise will use the templates bundled within the gem, see the next section to customise them.
 
 ```ruby
 # Gemfile
 gem 'premailer-rails'
 
-# config/environments/production.rb
+# config/application.rb
 Rails.application.configure do
-  config.action_mailer.raise_delivery_errors = false
-  config.action_mailer.default_url_options = { :host => host_domain, :port => port_number }
-  config.action_mailer.asset_host = your_apps_root_url
+  # Email configuration
   config.action_mailer.delivery_method = :smtp
-  ActionMailer::Base.smtp_settings = {
-    address:              'smtp.gmail.com',
-    port:                 587,
-    domain:               'gmail.com',
+
+  config.action_mailer.smtp_settings = {
+    address:              ENV['SMTP_HOST'],
+    port:                 ENV['SMTP_PORT'],
+    domain:               ENV['SMTP_DOMAIN'],
     user_name:            ENV['SMTP_USERNAME'],
     password:             ENV['SMTP_PASSWORD'],
     authentication:       'plain',
@@ -141,6 +153,13 @@ Rails.application.configure do
   }
 end
 
+# config/environments/<production|uat>.rb
+Rails.application.configure do
+  config.action_mailer.raise_delivery_errors = false
+  config.action_mailer.default_url_options = { host: host_domain, port: port_number }
+  config.action_mailer.asset_host = your_apps_root_url
+end
+
 # config/initializers/mno_enterprise.rb
 MnoEnterprise.configure do |config|
   config.mail_adapter = :smtp
@@ -150,22 +169,202 @@ end
 Rails.application.config.assets.precompile += %w( mno_enterprise/mail.css )
 ```
 
+
+In this example, the SMTP server settings are passed via environment variables. See sample configurations below.
+
+**Gmail**
+
+If you don't have access to a SMTP server, a personal Gmail account can be used as an alternative.
+The Gmail account should be set to allow "less secure apps".
+
+```ruby
+# config/application.yml
+SMTP_HOST: smtp.gmail.com
+SMTP_PORT: 587
+SMTP_DOMAIN: gmail.com
+SMTP_USERNAME: user@gmail.com
+SMTP_PASSWORD: password
+```
+
+**Mailgun**
+
+[Mailgun](https://www.mailgun.com/sending-email) provides an SMTP mode and allow you to manage multiple domain within the same account.
+
+```ruby
+# config/application.yml
+SMTP_HOST: smtp.mailgun.org
+SMTP_PORT: 587
+SMTP_DOMAIN: mg.acme-enterprise-mnoe-uat.maestrano.io
+SMTP_USERNAME:
+SMTP_PASSWORD:
+```
+
 ##### Customization of mail templates
-- You can override the default mail templates by adding template files ( template-name.html.erb, template-name.text.erb ) to the mail view directory (/app/views/system_notifications).
-- Logo can also be overriden by adding your own logo image (main-logo.png) to the image assets directory (/app/assets/images/mno_enterprise).
-- Write your own stylesheet by adding mail.css file to the stylesheets directory (/app/assets/stylesheets/mno_enterprise). The css rules you write will be applied to all the mail templates including the default ones.
+- You can override the default mail templates by adding template files (`template-name.html.erb`, `template-name.text.erb`) to the mail view directory (`/app/views/system_notifications`).
+- Logo can also be overridden by adding your own logo image (`main-logo.png`) to the image assets directory (`/app/assets/images/mno_enterprise`).
+- Write your own stylesheet by adding a `mail.css` file to the stylesheets directory (`/app/assets/stylesheets/mno_enterprise`). The css rules you write will be applied to all the mail templates including the default ones.
+
+### Intercom
+
+Intercom is already integrated in mno-enterprise, you just need to enable it!
+
+Add the gem to your `Gemfile`
+
+```ruby
+gem 'intercom', '~> 3.5.4'
+```
+
+Expose the following environments variables (via `application.yml` or your preferred method)
+
+```
+INTERCOM_APP_ID
+INTERCOM_TOKEN
+```
+
+If you want to enable secure mode (recommended), expose `INTERCOM_API_SECRET`.
+
+If you built your app with an older version of mno-enterprise, double-check that `config/initializer/mno-enteprise.rb` contains the following lines:
+
+```ruby
+# Intercom
+config.intercom_app_id = ENV['INTERCOM_APP_ID']
+config.intercom_api_secret = ENV['INTERCOM_API_SECRET']
+config.intercom_token = ENV['INTERCOM_TOKEN']
+```
+
+#### (Deprecated) Using API Keys
+
+Expose the following environments variables (via `application.yml` or your preferred method)
+
+```
+INTERCOM_APP_ID
+INTERCOM_API_KEY
+INTERCOM_API_SECRET
+```
+
+If you built your app with an older version of mno-enterprise, double-check that `config/initializer/mno-enteprise.rb` contains the following lines:
+
+```ruby
+# Intercom
+config.intercom_app_id = ENV['INTERCOM_APP_ID']
+config.intercom_api_secret = ENV['INTERCOM_API_SECRET']
+config.intercom_api_key = ENV['INTERCOM_API_KEY']
+```
+
+### Active Job Backend
+
+Maestrano Enterprise uses Active Job to process background jobs such as logging event or emails.
+
+By default if no adapter is set, the jobs are immediately executed.
+
+To see an up-to-date list of all queueing backend supported by Active Job see the documentation for [Active Job](http://edgeguides.rubyonrails.org/active_job_basics.html#backends)
+
+#### Sucker Punch
+
+This is the easiest as it runs within the application process, so you don't have to maintain a separate process to run background jobs.
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'sucker_punch', '~> 2.0'
+```
+
+To enable backward compatibility with ActiveJob 4.2, create the following initializer:
+
+```ruby
+# config/initializers/sucker_punch.rb
+
+require 'sucker_punch/async_syntax'
+```
+
+Then in `config/application.rb`:
+
+```ruby
+# Use Sucker Punch for ActiveJob
+config.active_job.queue_adapter = :sucker_punch
+```
+
+#### Sidekiq
+
+This is more involved as you need to manage a separate process (the sidekiq worker) and add Redis to your stack.
+
+Here's a quick start guide, see https://github.com/mperham/sidekiq/wiki/Active-Job for more details.
+
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'sidekiq'
+```
+
+Create a `config/sidekiq.yml`:
+
+```yaml
+---
+:queues:
+  - default
+  - mailers
+```
+
+In `config/application.rb`:
+
+```ruby
+# Use Sidekiq for ActiveJob
+config.active_job.queue_adapter = :sidekiq
+```
+
+Run the worker process, if you use a `Procfile` you can add the following line to it:
+
+```
+worker: bundle exec sidekiq
+```
+
+To enable the web interface only for admin, add to your `Gemfile`:
+
+```ruby
+gem 'sinatra', '~> 1.4.7', require: false
+```
+
+and to `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  ...
+
+  #================================================
+  # Sidekiq admin interface
+  #================================================
+  require 'sidekiq/web'
+  authenticate :user, -> (u) { u.admin_role == 'admin' } do
+    mount Sidekiq::Web, at: '/sidekiq'
+  end
+
+  ...
+end
+```
+
 
 ## Building the frontend
 The Maestrano Enterprise frontend is a Single Page Application (SPA) that is separate from the Rails project. The source code for this frontend can be found on the [mno-enterprise-angular Github repository](https://github.com/maestrano/mno-enterprise-angular)
 
 Build the frontend by running the following command:
 ```bash
-bundle exec rake mnoe:frontend:dist
+bin/rake mnoe:frontend:build
 ```
 This will create a "dashboard" directory under the /public folder with the compiled frontend.
 
 Building the frontend is only required if you modify the CSS and/or JavaScripts files under /frontend.
 
+### Upgrading the frontend
+
+To upgrade the frontend version, edit the `package.json` file if needed, then run:
+
+```
+bin/rake mnoe:frontend:update
+```
+
+This will upgrade the frontend version, respecting the constraint in `package.json`, and rebuild it.
+
 ## Modifying the style - Theme Previewer
 The Maestrano Enterprise Express frontend is bundled with a Theme Previewer allowing you to easily modify and save the style of an Express instance without reloading the page.
 
@@ -186,12 +385,14 @@ This action will save the current style in /frontend/src/app/stylesheets/theme-p
 
 ## Extending the Frontend
 You can easily override or extend the Frontend by adding files to the /frontend directory. All files in this directory will be taken into account during the frontend build and will override the base files of the mno-enterprise-angular project.
+You can also override the login page background adding an image and gif loaders, which is managed by rails,  including the files into the path ../app/assets/images/mno_enterprise. You can generate really cool gifs for this task in pages like http://loading.io/ .
+
 
 Files in this folder MUST follow the [mno-enterprise-angular](https://github.com/maestrano/mno-enterprise-angular) directory structure. For example, you can override the application layout by creating /frontend/src/app/views/layout.html in your project - it will override the original src/app/views/layout.yml file of the mno-enterprise-angular project.
 
 You can also add new files to this directory such as adding new views. This allows you to easily extend the current frontend to suit your needs.
 
-While extending the frontend, you can run this command to start the frontend using gulp serve and automatically override the original files with the ones in the frontend folder:
+While extending the frontend, you can run this command to start the frontend using gulp serve and automatically override the original files with the ones in the frontend folder(be aware it does not take into account images or folders):
 ```bash
 foreman start -f Procfile.dev
 ```
@@ -206,7 +407,7 @@ Simply copy the font files under the directory `/frontend/src/fonts/` of your ho
 
 An example of a project using a custom font can be seen on the [mno-enterprise-demo](https://github.com/maestrano/mno-enterprise-demo) project.
 
-NB: Your host project may have been generated or created before the implementation of this feature, in this case make sure the the file `/app/assets/stylesheets/main.less` contains:
+NB: Your host project may have been generated or created before the implementation of this feature, in this case make sure the file `/app/assets/stylesheets/main.less` contains:
 ```less
 // Import custom fonts
 //--------------------------------------------
@@ -224,12 +425,72 @@ In some cases you may decide that the current [mno-enterprise-angular](https://g
 
 In this case we recommend cloning or copying the [mno-enterprise-angular](https://github.com/maestrano/mno-enterprise-angular) repository in a new repository so as to keep the directory structure and build (Gulp) process. From there you can completely change the frontend appearance to fit your needs.
 
-Once done you can replace the frontend source by specifying your frontend github repository in the /bower.json file. You can then build it by running the usual:
+Once done you can replace the frontend source by specifying your frontend github repository in the /package.json file. You can then build it by running the usual:
 ```bash
-bundle exec rake mnoe:frontend:dist
+bin/rake mnoe:frontend:build
+```
+
+## Extending the Backend
+
+### Overriding Models and Controllers with the Decorator Pattern
+
+`mno-enteprise` follows the decorator pattern recommended in the [Engine Rails guide](http://guides.rubyonrails.org/engines.html#improving-engine-functionality)
+
+#### Using `ActiveSupport::Concern`
+
+Most of `mno-enteprise` classes use `ActiveSupport::Concern` making it really easy to extend them.
+
+For example look at the following `MnoEnterprise::Organization` class:
+
+```ruby
+module MnoEnterprise
+  class Organization < BaseResource
+    include MnoEnterprise::Concerns::Models::Organization
+  end
+end
 ```
 
-## Generating a database extension
+Let's say we want to add an extra method, a scope and not allow removal of users:
+
+```ruby
+# foobar-enterprise/app/models/mno_enterprise/organization.rb
+module MnoEnterprise
+  class Organization < BaseResource
+    include MnoEnterprise::Concerns::Models::Organization
+    
+    scope :big, -> { where('size.gt': 10) }
+    
+    def monkey_patched?
+     true
+    end
+    
+    # PATCH: do nothing
+    def remove_user(user)
+    end
+  end
+end
+```
+
+
+#### Using `Class#class_eval`
+
+Sometime the class you want to extend does not use a Concern. In this case, you can use `Class#class_eval`.
+
+For example, to override the `after_sign_in_path`:
+
+```ruby
+# foobar-enterprise/app/decorators/controllers/mno_enterprise/application_controller_decorator.rb
+MnoEnterprise::ApplicationController.class_eval do
+  # Patch: return to custom url
+  def after_sign_in_path_for(resource)
+    "my_custom_url"
+  end
+end
+```
+
+All decorators matching the glob `Dir.glob(Rails.root + "app/decorators/**/*_decorator*.rb")` are automatically loaded.
+
+### Generating a database extension
 
 If you want to add fields to existing models, you can create a database extension for it.
 
@@ -323,87 +584,6 @@ HealthCheck.setup do |config|
 end
 ```
 
-
-## Migrating from v2 to v3
-
-### a) Upgrade the gem
-First switch to a new branch such as v2-to-v3.
-```bash
-git co -b v2-to-v3
-```
-
-Open your Gemfile and ensure that your project points to the v3.0-dev branch of Maestrano Enterprise. You gemfile should look like this:
-```ruby
-gem 'mno-enterprise', git: 'https://some-token:x-oauth-basic@github.com/alachaum/mno-enterprise.git', branch: 'v3.0-dev'
-```
-
-Then update the gem by running
-```bash
-bundle update mno-enterprise
-```
-
-Ensure you've got node installed on your system. Some googling will surely provide you with the steps required to install Node on your machine.
-
-Rerun the Maestrano Enterprise task in your project. This task will download and compile the enterprise angular frontend.
-```bash
-bundle exec rake mno_enterprise:install
-```
-
-After running this task a new "/frontend" directory will have appeared in the root of your project. This folder will contain any customization you want to make the frontend. It should already contain a few LESS files with a default theme.
-
-### b) Reapply your style
-
-The way styling and frontend customisations are handled by the platform has changed. Everything is now located under the "/frontend" directory.
-
-In order to migrate your style, follow these instructions:
-
-- Copy the content of your /app/assets/stylesheets/theme.less.erb into /frontend/src/app/stylesheets/theme.less. Replace any ERB variable by the actual LESS value
-- Delete /app/assets/stylesheets/theme.less.erb
-- Copy the content of your /app/assets/stylesheets/variables.less into /frontend/src/app/stylesheets/variables.less.
-- Delete /app/assets/stylesheets/variables.less
-- Create the file: /app/assets/stylesheets/main.less and copy the following content to it:
-```less
-/*-----------------------------------------------------------------------*/
-/*                    Import Core LESS Framework                         */
-/*-----------------------------------------------------------------------*/
-// Import Core LESS Framework
-@import "mno_enterprise/main";
-
-/*-----------------------------------------------------------------------*/
-/*                           Customization                               */
-/*-----------------------------------------------------------------------*/
-
-// Import theme colors
-//--------------------------------------------
-@import "../../../frontend/src/app/stylesheets/theme";
-
-// Import custom variables
-//--------------------------------------------
-@import "../../../frontend/src/app/stylesheets/variables";
-
-// Import theme published by Theme Previewer
-//--------------------------------------------
-// @import "../../../frontend/src/app/stylesheets/theme-previewer-published.less";
-
-// Import any custom less file below
-//--------------------------------------------
-// @import 'homepage'
-```
-- Copy any CSS customization you have made in main.less.erb to main.less
-- Rebuild the frontend with your style
-```bash
-rake mnoe:frontend:dist
-```
-- Copy your logo in /app/assets/images/mno_enterprise/main-logo.png to /public/dashboard/images/main-logo.png
-
-Launch your application, your style should now be reapplied.
-
-### c) Caveat: Impac! endpoint
-
-The v3 is currently being finalised. There are some minor configuration options that still need to be implemented such as the "impact endpoint urls".
-
-If deploying to UAT, the Impac! URLs need to be manually replaced. Search the "/public" directory for "http://localhost:4000" and replace by "https://api-impac-uat.maestrano.io". Save the files and deploy.
-
 ## Contributing
 
 # Contributing to MnoEnterprise

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mno-enterprise
 version: !ruby/object:Gem::Version
-  version: 3.1.4
+  version: 3.2.0
 platform: ruby
 authors:
 - Arnaud Lachaume
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-05 00:00:00.000000000 Z
+date: 2017-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mno-enterprise-core
@@ -17,42 +17,42 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.1.4
+        version: 3.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.1.4
+        version: 3.2.0
 - !ruby/object:Gem::Dependency
   name: mno-enterprise-api
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.1.4
+        version: 3.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.1.4
+        version: 3.2.0
 - !ruby/object:Gem::Dependency
   name: mno-enterprise-frontend
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.1.4
+        version: 3.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.1.4
+        version: 3.2.0
 description: Maestrano Enterprise is your application marketplace, out of the box.
 email:
 - developers@maestrano.com
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Maestrano Enterprise