mno-enterprise 2.0.9 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 008ad4187ab05a27daf2109322a89fce704ffc37
-  data.tar.gz: 85cf01be4ae9af85fd43d91007227029fedc5ece
+  metadata.gz: b1c9ee072c828333593ecaf937167f8782215411
+  data.tar.gz: e473a347f6a3a126767133749d49abc3b51dd01e
 SHA512:
-  metadata.gz: f31fda64d58d2b045230866e714b7059634946ac20a11d1b85232eca927697c64bff440943ab6af5dedf8837f8983f1df00d2065d9f743616bb9dd1b08bcce69
-  data.tar.gz: e9af197408cf79bf430cf217db59ae00fe8916e02c4d3a9e3c5b9b0149c46b5dde2a923ca69f854bb6b1bb7379d6149100e5b7d27a4bf5ee0d5d9d41d677393c
+  metadata.gz: 90207df0a4bcb7e166e79d89b42a0739f1a9c4a6257399d72464e7c30edd17d6da224350bab914382d0c51797ad4485613de744d76daf46763a7fa8519813573
+  data.tar.gz: b9fc298122dceeca57591753cedcb82222ca9647a10032503110452b743e78baff2ddf6e6f39aebdd54ad2c7c5bd44d3e3b6f99f114fc49f75d87904cb53059d

data/README.md

@@ -1,20 +1,118 @@
-# mno-enterprise
-Maestrano Enterprise Engine
+<p align="center">
+<img src="https://raw.github.com/maestrano/maestrano-ruby/master/maestrano.png" alt="Maestrano Logo">
+<br/>
+<br/>
+</p>
+
+The Maestrano Enterprise Engine can be included in a Rails project to bootstrap an instance of Maestrano Enterprise Express.
+
+The goal of this engine is to provide a base that you can easily extend with custom style or logic.
+
+- - -
+
+1.  [Install](#install)
+2.  [Building the Frontend](#building-the-frontend)
+3.  [Modifying the style - Theme Previewer](#modifying-the-style---theme-previewer)
+4.  [Extending the Frontend](#extending-the-frontend)
+5.  [Replacing the Frontend](#replacing-the-frontend)
+6.  [Generating a database extension](#generating-a-database-extension)
+7.  [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)
+8.  [Migrating from v2 to v3](#migrating-from-v2-to-v3)
+9.  [Contributing](#contributing)
+
+- - -
 
 ## Install
 
+Create a new rails project:
+```ruby
+rails new name-enterprise
+```
+
 Add mno-enterprise to your Gemfile. A 'mno-enterprise-deployer-token' (Github oauth token) must have been generated by the 'mno-enterprise-deployer' github account.
 ```ruby
 # Maestrano Enterprise Engine
-gem 'mno-enterprise', git: 'https://<mno-enterprise-deployer-token>:x-oauth-basic@github.com/maestrano/mno-enterprise.git'
+gem 'mno-enterprise', git: 'https://<mno-enterprise-deployer-token>:x-oauth-basic@github.com/maestrano/mno-enterprise.git', branch: '3.0-dev'
 ```
 
 Run the install script
 ```bash
-$ rails g mno_enterprise:install
+rails g mno_enterprise:install
+```
+
+The install script will perform three things:
+- Propose popular gems to install (e.g. Rspec)
+- Generate an initializer for Maestrano Enterprise (config/initializers/mno_enterprise.rb)
+- Install and build the mno-enterprise-angular frontend
+- Install and build the admin dashboard frontend
+- 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.
+
+Once node is installed, you can run the following commands to ensure that all dependencies are installed:
+```bash
+npm install -g bower gulp gulp-util gulp-load-plugins del gulp-git phantomjs
 ```
 
-## Generate a database extension
+## 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
+```
+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.
+
+## 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.
+
+The Theme Previewer is available by accessing the following path: /dashboard/theme-previewer.html
+```
+e.g.: http://localhost:7000/dashboard/theme-previewer.html
+```
+
+Under the hood this Theme Previewer will modify the LESS files located under the /frontend directory.
+
+Two types of "save" actions are available in the Theme Previewer.
+
+**Save:**  
+This action will temporarily save the current style in /frontend/src/app/stylesheets/theme-previewer-tmp.less so as to keep it across page reloads on the Theme Previewer only. This action will NOT publish the style, meaning that it will NOT apply the style to the /dashboard/index.html page.
+
+**Publish:**  
+This action will save the current style in /frontend/src/app/stylesheets/theme-previewer-published.less and rebuild the whole frontend. This action WILL publish the style, meaning that it WILL apply the style to the /dashboard/index.html page.
+
+## 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.
+
+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:
+```bash
+foreman start -f Procfile.dev
+```
+
+This will accelerate your development as the gulp serve task use BrowserSync to reload the browser any time a file is changed.
+
+## Replacing the Frontend
+
+In some cases you may decide that the current [mno-enterprise-angular](https://github.com/maestrano/mno-enterprise-angular) frontend is not appropriate at all.
+
+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:
+```bash
+bundle exec rake mnoe:frontend:dist
+```
+
+## Generating a database extension
 
 If you want to add fields to existing models, you can create a database extension for it.
 
@@ -28,8 +126,12 @@ eg:
 rails g mno_enterprise:database_extension Organization growth_type:string
 ```
 
+## Deploying
+
+### Deploy a Puma stack on EC2 via Webistrano/Capistrano
+
+**IMPORTANT NOTE:** These are legacy instructions. They will soon be replaced by Docker instructions.
 
-## Deploy a Puma stack on EC2 via Webistrano/Capistrano
 First, prepare your server. You will find a pre-made AMI on our AWS accounts called "AppServer" or "Rails Stack" that you can use.
 
 Then, setup your new project via webistrano/capistrano.
@@ -52,9 +154,170 @@ This script will setup a bunch of symlinks for nginx, upstart and monit pointing
 
 That's it. You should be done!
 
-## Loader gif Reference
-**bg-main** - mno_enterprise/loader-32x32-bg-main.gif
-http://spiffygif.com/?color=ebe5ff&lines=8&bgColor=aeb5bf&length=4&radius=7&width=4&halo=false
+### Sample nginx config for I18n
+
+We need to accept URIs like `/en/dashboard` and serve `public/dashboard/index.html`.
+A simple combination of location regex and try_files does the trick.
+
+```
+server {
+  listen       80;
+  server_name  mnoe.mno.local;
+
+  root /apps/<%= app_name %>/current/public;
+  index        index.html index.htm;
+
+  location ~* "^/[A-Za-z]{2}/dashboard(.*)" {
+    try_files  /dashboard$1/index.html /dashboard$1.html /dashboard$1 @backend;
+  }
+
+  try_files  $uri/index.html $uri.html $uri @backend;
+```
+
+### Health Checks
+
+There are various endpoints to perform health checks:
+
+`/mnoe/ping`: A simple check to see that the app is up. Returns `{status: 'Ok'}`
+
+`/mnoe/version`: Version check. It will returns the version of the different components (app & mnoe gem):
+```json
+{
+  "app-version": "9061048-6811c4a",
+  "mno-enterprise-version": "0.0.1",
+  "env": "test"
+}
+```
+
+`/mnoe/health_check` & `/mnoe/health_check/full`: Complete health check (cache, smtp, database, ...). See [health_check](https://github.com/ianheggie/health_check)
+
+## 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 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
+
+We love pull requests from everyone. Here are some ways *you* can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code ( **no patch is too small** : fix typos, add comments, clean up inconsistent whitespace )
+* by refactoring code
+* by closing [issues][]
+* by reviewing patches
+
+[issues]: https://github.com/maestrano/mno-enterprise/issues
+
+## Submitting an Issue
+We use the [GitHub issue tracker][issues] to track bugs and features. Before
+submitting a bug report or feature request, check to make sure it hasn't
+already been submitted. When submitting a bug report, please include a [Gist][]
+that includes a stack trace and any details that may be necessary to reproduce
+the bug, including your gem version, Ruby version, and operating system.
+Ideally, a bug report should include a pull request with failing specs.
+
+[gist]: https://gist.github.com/
+
+## Submitting a Pull Request
+1. [Fork][fork] the [official repository][repo].
+2. [Create a topic branch.][branch]
+3. Write tests for your feature/bug.
+3. Implement your feature or bug fix.
+4. Run the specs with:
+```bash
+bundle exec rake test
+```
+4. Add, commit, and push your changes.
+5. [Submit a pull request.][pr]
+
+## Notes
+* Please add tests if you changed code. Contributions without tests won't be accepted.
+* Please don't update the Gem version.
+
+[repo]: https://github.com/maestrano/mno-enterprise/tree/master
+[fork]: https://help.github.com/articles/fork-a-repo/
+[branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
+[pr]: https://help.github.com/articles/using-pull-requests/
 
-**bg-inverse** - mno_enterprise/loader-32x32-bg-inverse.gif
-http://spiffygif.com/?color=977bf0&lines=8&length=4&radius=7&width=4&halo=false
+Inspired by https://github.com/thoughtbot/factory_girl/blob/master/CONTRIBUTING.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mno-enterprise
 version: !ruby/object:Gem::Version
-  version: 2.0.9
+  version: 3.0.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: 2016-04-05 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: 2.0.9
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.9
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: mno-enterprise-api
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.9
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.9
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: mno-enterprise-frontend
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.9
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.9
+        version: 3.0.0
 description: Maestrano Enterprise is your application marketplace, out of the box.
 email:
 - developers@maestrano.com
@@ -66,7 +66,7 @@ files:
 - lib/mno_enterprise/all.rb
 homepage: https://maestrano.com
 licenses:
-- Apache-2.0
+- Maestrano Enterprise License V1
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Maestrano Enterprise