gina 0.1.1-alpha.98 → 0.1.2-alpha.1

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2022 Rhinostone <contact@gina.io>
+Copyright (c) 2009-2023 Rhinostone <contact@gina.io>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README-4Contributors.md

@@ -68,9 +68,22 @@ Check if everything is working fine
 gina version
 ```
 
+Starting the framework
+
 ```tty
 gina start
 ```
+Or in debug mode 
+
+```tty
+gina start --inspect-gina
+```
+
+Retrieve logs
+
+```tty
+gina tail --keep-alive
+```
 
 #### Setting the framework default environment
 
@@ -88,6 +101,23 @@ This only means that if you omit the env in the command line while trying to sta
 > __NB:__ Unlike for the projects `envs`, the framework env list cannot be changed; it is `dev` or `prod`.
 
 
+### Debugging
+
+#### Framework
+```tty
+gina start --inspect-gina
+```
+
+#### Bundles
+
+> gina bundle:restart {bundle_name} @${project_name} --inspect=<port_number>
+
+```tty
+gina bundle:restart <bundle_name> @<project_name> --inspect=<port_number>
+```
+
+
+
 ### Publishing
 ---
 

package/README.md

@@ -1,14 +1,15 @@
 # Gina
-[![GitHub version](https://badge.fury.io/gh/Rhinostone%2Fgina.svg)](https://badge.fury.io/gh/Rhinostone%2Fgina) [![npm version](https://badge.fury.io/js/gina.svg)](https://badge.fury.io/js/gina)
+
+[![GitHub version](https://badge.fury.io/gh/Rhinostone%2Fgina.svg)](https://badge.fury.io/gh/Rhinostone%2Fgina) [![npm version](https://badge.fury.io/js/gina.svg)](https://badge.fury.io/js/gina) [![node version](https://badge.fury.io/node/v/gina.svg)](https://badge.fury.io/node/v/gina)
 
 <strong>Gina I/O</strong> - Node.js MVC and Event Driven framework
 
 > This is a `preview release`. We are looking for people to help us test and improve `Windows` support.
 > Meanwhile, __Windows users__ can use Docker or an alternative to run Gina and their projects.
-> 
+>
 > Some commands or features might not work since the framework is still under development & testing
-> 
-> We have some applications using the framework in production and we are improving our code in order to release the `1.0.0` version: which should come by the end of 2022. Thank you for your patience.
+>
+> We have some applications using the framework in production and we are improving our code in order to release the `1.0.0` version as soon as possible. Thank you for your patience.
 
 ## Philosophy behind
 
@@ -23,19 +24,50 @@ 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.__
+> For Linux & Mac OS X:
+> -  __the use of `sudo` is discouraged.__
+> - you should have a dedicated user such as `node` with its group `node`
+
+#### Versions
+
+| versions | description |
+|--------|--------|
+| alpha       | Preview release: ==not recomanded for production==      |
+| latest       | Latest stable relase        |
+
+#### 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 `gina` 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`
 
-#### 1st method (prefered)
+#### 2nd method - Classical
 
 ```  tty
 npm install -g gina@latest
 ```
 
+Or with a `nobody:nogroup` user (not recomanded for production)
+
+```  tty
+npm install -g --unsafe-perm gina@latest
+```
+
 __A few words about this method__
-Gina will try to install itself using the default $NPM_PREFIX. If the target is not writable, the prefix used will be updated for the time of the install process to `~/.npm-global` and restored back to your default $NPM_PREFIX after installation.
-This is why you should not get errors on installation.
+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.
 
-Still, __if you are not enterely satisfyied with this method__, you can setup permissions for your user in order to be able to write to : `$NPM_PREFIX/lib/node_modules`.
+__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 :
 
@@ -44,23 +76,21 @@ sudo chown -R $USER $(npm config get prefix)/lib/node_modules
 ```
 
 
-> __NB. :__ If you choose to use `sudo npm install -g gina`, you have to make sure that everytime you need to use the gina CLI, or if you use a specific command like `npm link gina`, you will have to do it with `sudo`.
+> __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.
 
-Then
-
-```  tty
-npm install -g gina@latest
-```
 
 
-#### 2nd method - Custom PREFIX
+You can now check if Gina is properly installed.
 
-This will install Gina in the user's home directory avoiding at the same time the need to use `sudo`.
-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
+```  tty
+gina version
+```
+or
+```  tty
+sudo gina version
 ```
+__NB.:__ This is a shortcut for `gina framework:version`
 
 
 
@@ -69,17 +99,23 @@ npm install -g gina@latest --prefix=~/.npm-global
 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
+npm install gina@latest
+```
+
+Or with a `nobody:nogroup` user (not recomanded for production)
+
+```  tty
+npm install --unsafe-perm 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
+You can now check if Gina is properly installed.
 
 ```  tty
-gina version
+./gina version
 ```
-__NB.:__ This is a shortcut for `gina framework:version`
+__NB.:__ This is a shortcut for `./gina framework:version`
 
 
 
@@ -147,6 +183,13 @@ You can start the bundle with the following command:
 gina bundle:start frontend @myproject
 ```
 
+> __Attention__
+> Default memory is 4 GB (4096 MB)
+> If you feel like you are going to need more [memory](https://blog.appsignal.com/2021/12/08/nodejs-memory-limits-what-you-should-know.html) for this particular bundle, let's say 8 GB:
+> ```tty
+> gina bundle:start frontend @myproject --max-old-space-size=8192
+> ```
+
 
 Now, visit http://127.0.0.1:3100/  to check your homepage.
 Isn't it sexy !?
@@ -175,7 +218,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.
 
@@ -189,10 +233,10 @@ Please, note that you have 2 types of environments : one for the framework, and
 
 > By default, Gina (the framework) comes with 2 environments : `dev` and `prod`. The default is `prod`. if you are [contributing](./README-4Contributors.md) to the framework or prototyping your application or service, we advise using the `dev` environment.
 > ```tty
-> gina framework:set --env=dev 
+> gina framework:set --env=dev
 > ```
 > ```tty
-> gina framework:set --log-level=debug 
+> gina framework:set --log-level=debug
 > ```
 
 You can check which are the environments set for your projects
@@ -225,6 +269,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
@@ -240,6 +285,27 @@ __Defining an existing environment as `development` (you can only have one like
 gina env:link-dev <your new dev env>
 ```
 
+__Benefits from using a `development` environment__
+You will not have to restart your bundle anytime you modify files inside directories like :
+- /controllers
+- /piblic
+- /templates
+
+### Region
+> __Attention :__ This will impact the logs output
+
+The default timezone is set to `Africa/Douala`.
+You can change it to your local timezone. For example, if you live in Johannesburg:
+
+```tty
+gina set --timezone=Africa/Johannesburg --date=yyyy/mm/dd
+```
+
+
+__Setup your bundle region preferences__
+Edit `myproject/src/<bundle>/config/settings.json` to match your preferences.
+
+
 ### Logs
 
 #### Getting the logs
@@ -249,7 +315,11 @@ __1st Method - The default one__
 ``` tty
 gina tail
 ```
+
 __NB.:__ This is an alias for `gina framework:tail`
+> __Attention__
+> Everytime a bundle exits, the tail process will be closed. To prevent tail from exiting, you can use the `--keep-alive` argument.
+> E.g.: `gina tail --keep-alive`
 
 By default, Gina does not store logs. Logs are treated like any other events then printed out to the `process.stdout`.
 
@@ -260,12 +330,15 @@ Note that this is optional since logs are output like for other frameworks: you
 So to handle log storage for your application, you have 2 options: see 2nd & 3rd Methods.
 
 __2nd Method - Old school way__
+
+> __Attention: __ You will have to handle yourself [log rotation](https://linux.die.net/man/8/logrotate)
+
 ```tty
-gina bundle:start frontend @myproject > /usr/local/var/log/gina/frontend.myproject.domain.log 2>&1
+gina bundle:start frontend @myproject --log > /usr/local/var/log/gina/frontend.myproject.app.log 2>&1
 ```
 You can now check
 ```tty
-tail - f /usr/local/var/log/gina/frontend.myproject.domain.log
+tail - f /usr/local/var/log/gina/frontend.myproject.app.log
 ```
 
 __3rd Method - Create your own container/transport by extending gina default container__
@@ -306,13 +379,17 @@ gina framework:set --log-level=debug
 ## HTTPS, HTTP/2 and certificates
 
 ### Installing a certificate
+
+> __Attention__
+> ==One certificate per bundle/service==
+
 You now want to install a certificate for your project in order to run your project with HTTPS scheme or with HTTP/2 protocol ?
-At this moment, Gina does not generate a cetificate for you, but you can use a service like [sslforfree](https://www.sslforfree.com) to genreate a free 90 days certificate, then install it into your Gina home directory depending on the scope of your host (targeted machine: local or production). 
+At this moment, Gina does not generate a cetificate for you, but you can use a service like [sslforfree](https://www.sslforfree.com) to genreate a free 90 days certificate, then install it into your Gina home directory depending on the scope of your host (targeted machine: local or production).
 [SSL For Free](https://www.sslforfree.com) will provide you with a folder named with the domain you have used to setup your certificate. You just need to paste its content into the right location.
 
 The directory should be located @`~/.gina/certificates/scopes`.
 By default, `local` scope is set. But when you will go live, you should set the scope to production and paste your certificate into the right folder.
-__E.g:__ The `myproject.domain` folder should be placed into:
+__E.g:__ The `frontend.myproject.app` folder should be placed into:
 - `~/.gina/certificates/scopes/local` for your dev host
 - `~/.gina/certificates/scopes/production` for you production host
 
@@ -356,10 +433,10 @@ Error: unable to get issuer certificate
     at TLSSocket.onConnectSecure (node:_tls_wrap:1530:34)
     at TLSSocket.emit (node:events:390:28)
     at TLSSocket._finishInit (node:_tls_wrap:944:8)
-    at TLSWrap.ssl.onhandshakedone (node:_tls_wrap:725:12) 
+    at TLSWrap.ssl.onhandshakedone (node:_tls_wrap:725:12)
 ```
 
-Do not panic, and follow the steps provided in the following section.
+Do not panic, and follow the steps to solve this issue are provided in the following section.
 
 ### Local scope & certificate consideration
 > __Ignore__ the following instructions __if you can start your application__ without any certificate errors.
@@ -367,12 +444,14 @@ Do not panic, and follow the steps provided in the following section.
 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 downloaded your certificates from __[Ssl For Free](https://sslforfree.com)__ which you have then placed under: `~/.gina/certificates/scopes/local/myproject.domain`.
+__Attention:__ We are assuming that for the following example, you have a wildcard certificate. If this is not possible, you will have to generate a certificate for each bundle and treat each bundle like a subdomain.
+
+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/frontend.myproject.app`.
 
 __Step 1__
 Go to the folder
 ```tty
-cd ~/.gina/certificates/scopes/local/myproject.domain
+cd ~/.gina/certificates/scopes/local/frontend.myproject.app
 ```
 
 List your files
@@ -396,11 +475,11 @@ Go to the `Generate the Correct Chain` tool.
 Paste the content you have just copied out of your `certificate.crt` into the field, then __do not forget to check the option__ `Include Root Certificate`.
 
 __It will download a chained certificate__.
-Rename it to `certificate.chained+root.crt` and copy/paste the file to your certificates location (~/.gina/certificates/scopes/local/myproject.domain)
+Rename it to `certificate.chained+root.crt` and copy/paste the file to your certificates location (~/.gina/certificates/scopes/local/frontend.myproject.app)
 
 __Step 2__
 You now need to combine your private key with your new certificate
-Still @ `~/.gina/certificates/scopes/local/myproject.domain` ?
+Still @ `~/.gina/certificates/scopes/local/frontend.myproject.app` ?
 
 ```tty
 cat private.key certificate.chained+root.crt > certificate.combined.pem
@@ -425,6 +504,13 @@ Do this for all of you `myproject`'s bundles, then restart your bundles
 gina bundle:restart @myproject
 ```
 
+__Remember__
+You will need a certificate for each bundle/service, unless you get a `wildcard certificates`.
+If you have a  `wildcard certificates`, you only need to follow the folling steps once, then create a symling for each bundle/service to the main certificate.
+
+```tty
+ln -s ~/.gina/certificates/scopes/local/myproject.app ~/.gina/certificates/scopes/local/frontend.myproject.app
+```
 
 ### Uninstalling Gina
 
@@ -493,7 +579,7 @@ More documentation and tutorials are coming soon !
 
 ## License (MIT)
 
-Copyright © 2009-2022 [Rhinostone](http://www.rhinostone.com/)
+Copyright © 2009-2023 [Rhinostone](http://www.rhinostone.com/)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal