gina 0.1.1-alpha.13 → 0.1.1-alpha.132

package/AUTHORS

@@ -2,5 +2,6 @@
 # project in one way or another.
 #
 
-Martin Luther ETOUMAN <m.etouman@rhinostone.com>
+Martin Luther ETOUMAN <martin-luther.etouman@gina.io>
+Fabrice Delaneau <fabrice.delaneau@gina.io>
 Stephane HEAV <stephane.heav@gmail.com>

package/README.md

@@ -23,18 +23,81 @@ Note that Gina does not rely on Connect or ExpressJS, still, you can use all plu
 ### Installing Gina
 Gina aims to be at the same time a framework, a deployment and monitoring environment for your projects. So, to fully enjoy Gina, we recommend that you install it with the `-g` option.
 > For Microsoft Windows, you might have to run the command line with Administrator privileges.
+> For Linux & Mac OS X, __the use of `sudo` is discouraged.__
+
+#### 1st method (prefered) - Custom PREFIX
+
+This will install Gina in the user's home directory avoiding at the same time the need to use `sudo` or the `root` user.
+By adding at the end the `--reset` argument, you will ensure a factory reset for the `~/.gina` preferences folder: all preferences will be lost, but your existing projects will not be erased.
+
+```tty
+npm install -g gina@latest --prefix=~/.npm-global
+```
+
+You can now check if Gina is properly installed.
+
+```  tty
+gina version
+```
+__NB.:__ This is a shortcut for `gina framework:version`
+
+#### 2nd method - Classical
 
 ```  tty
 npm install -g gina@latest
 ```
 
-You can check if Gina is properly installed
+__A few words about this method__
+This method is mainly used if you wish to install gina with the `root` user.
+Gina will try to install itself using the default $NPM_PREFIX (`/usr/local`). If the target is not writable you will get permission errors.
+
+__Note that for this method__, if the user is not `root`, you can setup permissions for your user in order to be able to write to : `$NPM_PREFIX/lib/node_modules`.
+
+If you don't already have done it, you should start with :
+
+```tty
+sudo chown -R $USER $(npm config get prefix)/lib/node_modules
+```
+
+
+> __Important :__ If you choose to use `sudo npm install -g gina`, you will also have to use the `sudo` for specific commands like `npm link gina`.
+> Again, the use of `sudo` is discouraged.
+
+
+
+You can now check if Gina is properly installed.
+
 ```  tty
 gina version
 ```
+or
+```  tty
+sudo gina version
+```
 __NB.:__ This is a shortcut for `gina framework:version`
 
 
+
+#### 3rd method - local to your project
+
+If you feel like you do not need to install globally Gina for some reasons like only using the framework for a single project, you can install Gina without the `-g` argument.
+Go to your project's root and tap:
+```tty
+npm instal gina@latest
+```
+
+__Attention:__  to use gina CLI, you will need to run it from your project location since the CLI was not installed with the global argument `-g`.
+
+You can now check if Gina is properly installed.
+
+```  tty
+./gina version
+```
+__NB.:__ This is a shortcut for `./gina framework:version`
+
+
+
+
 ### Starting the framework
 Gina is at the same time a framework and a server.
 By starting the framework, you will also start the server.
@@ -50,6 +113,11 @@ A project is a collection of bundles (applicaitons or services). See it as a rep
 
 Let's create our first project and install Gina.
 
+```tty
+cd ~/.Sites
+```
+
+
 ``` tty
 mkdir myproject && cd myproject
 ```
@@ -82,7 +150,7 @@ Ok ! Let's do it !
 ``` tty
 gina bundle:add frontend @myproject
 ```
-__NB.:__ If you are launching the command from the project directory, you don't need `@myproject`. The same goes for all bundles commands.
+__NB.:__ If you are launching the command from the project directory, you don't need to add `@myproject`. The same goes for all bundles commands.
 
 We have just created a frontend application that will host our homepage.
 You will find all bundle sources under `myproject/src`.
@@ -121,7 +189,8 @@ Then restart your bundle
 gina bundle:restart frontend @myproject
 ```
 
-Now edit the `home` control in `src/frontend/controllers/controller.js` so that you can have `self.render(...)` instead of `self.renderJSON(...)`
+Now edit the `home` control in `src/frontend/controllers/controller.content.js` so that you can have `self.render(...)` instead of `self.renderJSON(...)`
+
 
 Once it's done, you just need to refresh your browser.
 
@@ -137,6 +206,9 @@ Please, note that you have 2 types of environments : one for the framework, and
 > ```tty
 > gina framework:set --env=dev 
 > ```
+> ```tty
+> gina framework:set --log-level=debug 
+> ```
 
 You can check which are the environments set for your projects
 ```tty
@@ -168,6 +240,7 @@ gina env:use prod @myproject
 __NB.:__ If you need to change it for a particular bundle, you still can do it at runtime using `--env=<your env>` to override the default settings. This will not set `<your env>`as the default environment for the whole project.
 
 
+
 #### Other operations you can apply to your environment:
 __Adding a new environment for your project__
 ```tty
@@ -183,8 +256,18 @@ __Defining an existing environment as `development` (you can only have one like
 gina env:link-dev <your new dev env>
 ```
 
-### Getting the logs
-You will also get logs related to your running bundles.
+__Benefits from using a `development` environment__
+You will not have to restart your bundle anytime you modify files inside directories like :
+- /controllers
+- /piblic
+- /templates
+
+### Logs
+
+#### Getting the logs
+You will get logs for the framework and related to your running bundles.
+
+__1st Method - The default one__
 ``` tty
 gina tail
 ```
@@ -196,8 +279,9 @@ This means that if you need Gina to handle logs storage, you need a logger conta
 
 Note that this is optional since logs are output like for other frameworks: you can catch those while writing your daemon starting script on you production server.
 
-So to handle log storage for your application, you have 2 options.
-__1) Old school way__
+So to handle log storage for your application, you have 2 options: see 2nd & 3rd Methods.
+
+__2nd Method - Old school way__
 ```tty
 gina bundle:start frontend @myproject > /usr/local/var/log/gina/frontend.myproject.domain.log 2>&1
 ```
@@ -206,7 +290,7 @@ You can now check
 tail - f /usr/local/var/log/gina/frontend.myproject.domain.log
 ```
 
-__2) Create your own container/transport by extending gina default container__
+__3rd Method - Create your own container/transport by extending gina default container__
 
 
 If you still want gina to handle logs storage, you are lucky, we have developped a file container/transport that you just need to enable.
@@ -223,6 +307,24 @@ gina restart
 
 __NB.: __For development purposes, using the CLI `gina tail` is still a better option because you will have a better overview of what is really going on for all your application at once & for the framework.
 
+#### Setting default log level
+
+By default Gina is set to `info`. Here is the list of available log level hierarchies.
+
+| levels | Included messages |
+|--------|--------|
+| trace  | Emergency, Alert, Critical, Error, Warning, Notice, Informational, Debug        |
+| debug  | Emergency, Alert, Critical, Error, Warning, Notice, Informational, Debug       |
+| info   | Emergency, Alert, Critical, Error, Warning, Notice, Informational       |
+| warn   | Emergency, Alert, Critical, Error, Warning, Notice       |
+| error  | Emergency, Alert, Critical, Error, Notice     |
+| fatal  | Emergency, Alert, Critical, Notice       |
+
+If you are at the developpemnt stage of your project, you might want to get all debug messages.
+```tty
+gina framework:set --log-level=debug
+```
+
 ## HTTPS, HTTP/2 and certificates
 
 ### Installing a certificate
@@ -240,7 +342,7 @@ __E.g:__ The `myproject.domain` folder should be placed into:
 ### Enable HTTPS scheme
 > __NB.:__ `certificate` is `required`.
 > By enabling HTTPS, you will do so for your entire poroject by default, but you can later set one per application.
-> And if you want to run your experimental HTTP2 implementation, you will need HTTS scheme.
+> And if you want to run our experimental HTTP2 implementation, you will need HTTPS scheme.
 
 Check what is your actual scheme & protocol status
 ```tty
@@ -282,12 +384,12 @@ Error: unable to get issuer certificate
 Do not panic, and follow the steps provided in the following section.
 
 ### Local scope & certificate consideration
-Ignore the following instructions if you can start your application without any certificate errors.
+> __Ignore__ the following instructions __if you can start your application__ without any certificate errors.
 
-This is `important` and you will have to take additional steps to make your certificate fully valid __while developping on your `local/dev host`__.
+This is __important__ and you will have to take additional steps to make your certificate fully valid __while developping on your `local/dev host`__.
 Since in most cases you will not have the `Root Certificate` included in your certificate, you need to generate a correct certificate including the Root Certificate. __For production, it will not be a problem__ since the Root certificate is provided by the client browser.
 
-Let say that you have downloded your certificates from __[Ssl For Free](https://sslforfree.com)__ which you have then placed under: `~/.gina/certificates/scopes/local/myproject.domain`.
+Let say that you have downloaded your certificates from __[Ssl For Free](https://sslforfree.com)__ which you have then placed under: `~/.gina/certificates/scopes/local/myproject.domain`.
 
 __Step 1__
 Go to the folder
@@ -305,11 +407,11 @@ Output should look like
 ca_bundle.crt	certificate.crt	private.key
 ```
 
-
+Now, copy the content of `certificate.crt`
 ```tty
 cat certificate.crt
 ```
-Copy the content of `certificate.crt`
+
 
 Visit [https://whatsmychaincert.com](https://whatsmychaincert.com)
 Go to the `Generate the Correct Chain` tool.
@@ -335,7 +437,7 @@ We just need to override Gina default certificate paths
 ```tty
 {
     // "privateKey": "{GINA_HOMEDIR}/certificates/scopes/{scope}/{host}/private.key",
-    "certificate": "{GINA_HOMEDIR}/certificates/scopes/{scope}/{host}/certificate.chained+root.crt",
+    // "certificate": "{GINA_HOMEDIR}/certificates/scopes/{scope}/{host}/certificate.crt",
     "ca": "{GINA_HOMEDIR}/certificates/scopes/{scope}/{host}/certificate.combined.pem"
 }
 ```
@@ -346,9 +448,33 @@ gina bundle:restart @myproject
 ```
 
 
+### Uninstalling Gina
+
+> For Microsoft Windows, you might have to run the command line with Administrator privileges.
+
+__Wihtout prefix__
+```  tty
+npm uninstall -g gina
+```
+
+Or if you have an Error like `EACCESS: permission denied, mkdir '/usr/local/lib/node_modules/gina'`
+
+__With prefix - If Gina was installed with a prefix__
+```tty
+npm uninstall -g gina --prefix=~/.npm-global
+```
+
+
+
 
 ## Troubleshooting
 
+### My settings are broken, I need a fresh install with the default settings
+```tty
+npm install -g gina@latest --reset
+```
+
+
 ### I can't start my bundle
 
 __Are you starting for the first time ?__
@@ -356,14 +482,14 @@ __Are you starting for the first time ?__
 - If you are a __Windows user__, make sure you are running your command line with sufficient permission; like __"launching your terminal as administrator"__.
 
 
-- If you have just cloned Gina from GitHub, don't forget to run from the project root :
+- If you have just cloned Gina from GitHub, don't forget to run from the framework root :
 
 ```tty
-node node_modules/gina/script/pre_install.js
+node node_modules/gina/script/pre_install.js -g
 ```
 
 ```tty
-node node_modules/gina/script/post_install.js
+node node_modules/gina/script/post_install.js -g
 ```
 
 

package/bin/cli

@@ -4,10 +4,11 @@
 var fs          = require('fs');
 var net         = require('net');
 var util        = require('util');
+var os          = require("os");
 var promisify   = util.promisify;
 
 async function onExec() {
-    
+
     // process.stdout.write('GINA CLI LOADED !! ' + JSON.stringify(process.argv, null, 2) + '\n');
 
     var isWin32         = (process.platform === 'win32') ? true : false;
@@ -18,13 +19,17 @@ async function onExec() {
     // loading pack
     var pack            = ginaPath + '/package.json';
     pack = (isWin32) ? pack.replace(/\//g, '\\') : pack;
-    var home            = getUserHome();// jshint ignore:line
+    var home            = null;
     var frameworkPath   = null;
-    
+
     var debugPort           = null
         , debugBrkEnabled   = false
         , isUpdateRequired  = false
         , params            = process.argv
+        , settings          = null
+        , hostname          = os.hostname() // by default
+        , hostV4            = null
+        , mqPort            = null
     ;
     try {
         var packObj         = require(pack);
@@ -33,53 +38,99 @@ async function onExec() {
         var generator   = require(frameworkPath + '/lib/generator');
 
         require(frameworkPath + '/lib');
-        var aliases     = require(frameworkPath + '/lib/cmd/aliases.json');
-        
+        // var aliases     = require(frameworkPath + '/lib/cmd/aliases.json');
+
         // catching debug|inspect arg
-        //process.stdout.write('params '+ params.join(', ') + '\n');    
+        //process.stdout.write('params '+ params.join(', ') + '\n');
         if ( params.length > 0 ) {
             for (var p = 0, len = params.length; p < len; ++p) {
-                
+
                 if ( /^\-\-port/.test(params[p]) ) {
                     let port = params[p].split(/\=/)[1];
                     setEnvVar('GINA_PORT', ~~port);// jshint ignore:line
-                    isUpdateRequired = true;            
+                    isUpdateRequired = true;
+                    continue;
+                }
+
+                if ( /^\-\-mq\-port/.test(params[p]) ) {
+                    let mqPort = params[p].split(/\=/)[1];
+                    setEnvVar('GINA_MQ_PORT', ~~mqPort);// jshint ignore:line
+                    isUpdateRequired = true;
+                    continue;
+                }
+
+                if ( /^\-\-host\-v4/.test(params[p]) ) {
+                    let host = params[p].split(/\=/)[1];
+                    setEnvVar('GINA_HOST_V4', host);// jshint ignore:line
+                    isUpdateRequired = true;
+                    continue;
+                }
+
+                if ( /^\-\-hostname/.test(params[p]) ) {
+                    hostname = params[p].split(/\=/)[1];
+                    setEnvVar('GINA_HOSTNAME', hostname);// jshint ignore:line
+                    isUpdateRequired = true;
                     continue;
                 }
-                
+
                 if ( /^\-\-debug(\_|\-)port/.test(params[p]) ) {
                     let port = params[p].split(/\=/)[1];
                     setEnvVar('GINA_DEBUG_PORT', ~~port);// jshint ignore:line
-                    isUpdateRequired = true;            
+                    isUpdateRequired = true;
                     continue;
                 }
-                
+
                 if ( /^\-\-(inspect|debug)/.test(params[p]) ) {
                     debugBrkEnabled = ( /\-brk/.test(params[p]) ) ? true : false;
                     debugPort       = params[p].split(/\=/)[1];
-                    params.splice(p,1);            
+                    params.splice(p,1);
                     break;
                 }
             }
         }
-        
+
+
 
         var shortVersion = version.split('.');
         shortVersion.splice(2);
         shortVersion = shortVersion.join('.');
         setEnvVar('GINA_SHORT_VERSION', shortVersion);// jshint ignore:line
-        
-        
+
+        home = getUserHome();// jshint ignore:line
         if ( typeof(getEnvVar('GINA_HOMEDIR')) == 'undefined') {// jshint ignore:line
             setEnvVar('GINA_HOMEDIR', home + '/.gina')// jshint ignore:line
         }
         home = getEnvVar('GINA_HOMEDIR');// jshint ignore:line
-        
-        var settingsPath =  _( home +'/'+ shortVersion +'/settings.json', true );// jshint ignore:line
-        var settings = requireJSON(settingsPath);// jshint ignore:line
-        
+
+        settings = { 'log_level': 'info'}; // First time launch or reset
+        if ( new _( home +'/'+ shortVersion +'/settings.json', true ).existsSync() ) {// jshint ignore:line
+            var settingsPath =  _( home +'/'+ shortVersion +'/settings.json', true );// jshint ignore:line
+            settings = requireJSON(settingsPath);// jshint ignore:line
+        }
+
+
         setEnvVar('GINA_LOG_LEVEL', settings['log_level']);// jshint ignore:line
         setEnvVar('GINA_VERSION', version);// jshint ignore:line
+        setEnvVar('GINA_RUNDIR', settings['rundir']);// jshint ignore:line
+        setEnvVar('GINA_LOGDIR', settings['logdir']);// jshint ignore:line
+        setEnvVar('GINA_TMPDIR', settings['tmpdir']);// jshint ignore:line
+
+        // prior to what settings says
+        if (hostname != settings['hostname'] && !isUpdateRequired) {
+            setEnvVar('GINA_TMPDIR', settings['hostname']);// jshint ignore:line
+            hostname = settings['hostname'];
+        }
+        hostV4 = getEnvVar('GINA_HOST_V4') || settings['host_v4'] || '127.0.0.1';// jshint ignore:line
+        mqPort = getEnvVar('GINA_MQ_PORT')|| settings['mq_port'] || 8125;// jshint ignore:line
+
+        if ( typeof(packObj.config) != 'undefined' ) {
+            if (typeof(packObj.config.prefix) != 'undefined' ) {
+                setEnvVar('GINA_PREFIX', packObj.config.prefix);// jshint ignore:line
+            }
+            if ( typeof(packObj.config.globalMode) != 'undefined' ) {
+                setEnvVar('GINA_GLOBAL_MODE', packObj.config.globalMode);// jshint ignore:line
+            }
+        }
 
         // Loading logger.
         console = lib.logger;// jshint ignore:line
@@ -88,16 +139,15 @@ async function onExec() {
             console.pauseReporting();
         }
         console.setLevel(settings['log_level'], 'gina');
-                
+
         // Loading logger listner vs ~/.gina/user/extensions/logger/mq/config.json & ~/.gina/{shortVersion}/settings.json
         if ( /(gina\/bin\/cli|gina\/\/bin\/gina)$/.test(process.argv[1]) ) {
-            
+
             var MQListener = require(frameworkPath + '/lib/logger/src/containers/mq/listener.js');
-            
-            var mqPort = 8125;
-            var mqListener = await new MQListener({ port: 8125 });
+
+            var mqListener = await new MQListener({ port: mqPort, host: hostV4 });
             // required for tail command
-            var mqPortFile = './tmp/mq-listener-v'+ version +'.port';
+            var mqPortFile = getTmpDir() + '/mq-listener-v'+ version +'.port';// jshint ignore:line
             console.debug('Writting: '+ mqPortFile);
             fs.writeFileSync( mqPortFile, ''+mqPort );
             process.on('exit', function() {
@@ -106,7 +156,7 @@ async function onExec() {
                 mqListener.unref();
             })
         }
-        
+
         if ( !fs.existsSync(frameworkPath) ) {
             console.alert('Could not find version ' + version + '.\nFirst try:\n$ gina framework:install ' + version);
             process.exit(1)
@@ -127,7 +177,8 @@ async function onExec() {
     filterArgs();// jshint ignore:line
     //check for $HOME path, alert if empty.
     if (!home) {
-        console.error('No ' + ((isWin32) ? 'USERPROFILE' : 'HOME') + ' path found.')
+        console.error('No ' + ((isWin32) ? 'USERPROFILE' : 'HOME') + ' path found.');
+        process.exit(1);
     } else {
         setEnvVar('GINA_HOMEDIR', home);// jshint ignore:line
         setEnvVar('GINA_DIR', ginaPath);// jshint ignore:line
@@ -136,19 +187,27 @@ async function onExec() {
     }
     setEnvVar('GINA_IS_WIN32', isWin32, true);// jshint ignore:line
 
-    if (isUpdateRequired) {    
-        settings['port'] = getEnvVar('GINA_PORT') || null;// jshint ignore:line
-        settings['debug_port'] = getEnvVar('GINA_DEBUG_PORT') || null;// jshint ignore:line
-        console.debug('Updating debug settings: #'+  getEnvVar('GINA_DEBUG_PORT'));// jshint ignore:line
+    if (!settings) {
+        settings = requireJSON(settingsPath);// jshint ignore:line
+    }
+    if (isUpdateRequired) {
+        console.debug('Updating debug settings ...');// jshint ignore:line
+        settings['port'] = getEnvVar('GINA_PORT') || settings['port'] || null;// jshint ignore:line
+        settings['debug_port'] = getEnvVar('GINA_DEBUG_PORT') || settings['debug_port'] || null;// jshint ignore:line
+
+        settings['mq_port'] = getEnvVar('GINA_MQ_PORT') || settings['mq_port'] || null;// jshint ignore:line
+        settings['host_v4'] = getEnvVar('GINA_HOST_V4') || settings['host_v4'] || null;// jshint ignore:line
+        settings['hostname'] = getEnvVar('GINA_HOSTNAME') || settings['hostname'] || null;// jshint ignore:line
         generator.createFileFromDataSync(settings, settingsPath);// jshint ignore:line
     }
 
 
     /**
      * Framework port
+     * To change it: gina framework:set --port=<port_number>
      * TODO - Add a port scanner & compare with ~/.gina/{shortVersion}/settings.json on `post_install`
      * */
-    var port = 8124;
+    var port = settings['port'] || 8124;
 
     // |-> framework/{version}/lib/cmd
     var allowedOffline = [
@@ -194,11 +253,14 @@ async function onExec() {
             frameworkPath   : frameworkPath,
             homedir         : home,
             port            : port,
+            hostV4          : hostV4,
+            mqPort          : mqPort,
+            hostname        : hostname,
             debugPort       : debugPort,
             debugBrkEnabled : debugBrkEnabled,
             pack            : pack
         });
-        
+
 
     } else if (
         typeof(process.argv[2]) != 'undefined'
@@ -207,13 +269,16 @@ async function onExec() {
         || process.argv[2].substr(0, 2) === '--'
         || process.argv[2].substr(0, 1) === '-'
     ) {
-            
+
         require(binPath + '/cmd')({
             binPath         : binPath,
             ginaPath        : ginaPath,
             frameworkPath   : frameworkPath,
             homedir         : home,
             port            : port,
+            hostV4          : hostV4,
+            mqPort          : mqPort,
+            hostname        : hostname,
             debugPort       : debugPort,
             debugBrkEnabled : debugBrkEnabled,
             pack            : pack
@@ -228,27 +293,27 @@ async function onExec() {
     } else {
 
         //Connect to framework.
-        var client = net.connect({port: port},
+        var client = net.connect({port: port, host: hostV4},
             function() {
                 //Forwarding cmd.
                 // retieving debug infos
                 var debugOption = null;
                 if ( debugPort ) {
-                    debugOption = '--inspect=' + debugPort;     
-                        
+                    debugOption = '--inspect=' + debugPort;
+
                     if (debugBrkEnabled) {
                         debugOption = debugOption.replace(/\-\-inspect/, '--inspect-brk')
                     }
-                    
+
                     process.argv.push(debugOption)
                 }
-                
+
                 client.write( JSON.stringify(process.argv) );
             }
         );
 
-        client.on('data', function(data) {       
-            
+        client.on('data', function(data) {
+
             //Acknowledging ready state.
             if ( /\[ quit \]/.test(data) ) {
                 client.end();
@@ -262,7 +327,7 @@ async function onExec() {
                 client.end();
                 return
             }
-            
+
         });
 
         //client end event.
@@ -276,11 +341,11 @@ async function onExec() {
             } else {
                 console.log('[ gina ] not started, try to start framework with :\n$ sudo gina start')
             }
-            
+
             console.debug(err.stack||err);
-            
+
             process.exit(1)
-        });    
+        });
     }
 }
 

package/bin/cli-debug

@@ -3,7 +3,7 @@
 /**
  * Mainly used to debug framework CMD lib - default port should be #5858 by default
  * To modify the debug port :
- * 
+ *
  * $ gina framework:set --debug-port=<your new debug port>
  */
 const fs    = require('fs');
@@ -34,16 +34,16 @@ var params = argv.split(/\s+/g);
 if ( params.length > 0 ) {
     for (var p = 0, len = params.length; p < len; ++p) {
         if ( /^\-\-port/.test(params[p]) ) {
-            setEnvVar('GINA_PORT', ~~params[p].split(/\=/)[1]);
+            setEnvVar('GINA_PORT', ~~params[p].split(/\=/)[1]);// jshint ignore:line
             continue;
         }
         if ( /^\-\-debug(\_|\-)port/.test(params[p]) ) {
-            setEnvVar('GINA_DEBUG_PORT', ~~params[p].split(/\=/)[1]);
+            setEnvVar('GINA_DEBUG_PORT', ~~params[p].split(/\=/)[1]);// jshint ignore:line
             continue;
         }
         if ( /^\-\-(inspect|debug)/.test(params[p]) ) {
             debugPort = ~~params[p].split(/\=/)[1];
-            process.argv.splice(p,1);   
+            process.argv.splice(p,1);
         }
     }
 }