Gina

Documentation: https://gina.io/docs/

Gina I/O - Node.js MVC and Event Driven framework

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.

Philosophy behind

Gina was designed to be accessible, flexible, scalable and maintainable. Our main purpose was to allow developers to create easier and faster web applications.

Gina comes with essential features at this moment, but most of the things we don't have yet can be replaced by some alternatives written in other languages like: Ruby, PHP, .net, Python or C++. You are free to use such alternatives until we implement similar features.

Note that Gina does not rely on Connect or ExpressJS, still, you can use all plugins or middlewares designed for those frameworks ;-)

Getting started with Gina I/O

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.
• you should have a dedicated user such as node with its group node

Versions

| versions | description | | -------- | -------------------------------------------------------- | | alpha | Preview release: not recommended for production | | latest | Latest stable release |

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.

npm install -g gina@latest --prefix=~/.npm-global

You can now check if Gina is properly installed.

gina version

NB.: This is a shortcut for gina framework:version

2nd method - Classical

npm install -g gina@latest

Or with a nobody:nogroup user (not recommended for production)

npm install -g --unsafe-perm gina@latest

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 :

sudo chown -R $USER $(npm config get prefix --quiet)/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.

gina version

or

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:

npm install gina@latest

Or with a nobody:nogroup user (not recommended for production)

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.

./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.

gina start

NB.: This is an alias for gina framework:start

Initializing a project

A project is a collection of bundles (applications or services). See it as a representation of your domain.

Let's create our first project and install Gina.

We will initialize our project under ~/Sites

On Windows from the Windows CLI, you might need admin privileges.

gina project:add @myproject --path=~/Sites/myproject

If you need to remove this project later

gina project:rm @myproject

Creating a bundle (application or service)

A project is a set of bundles. Gina lets you create all kinds of bundles :

• API & web services
• frontend & backend applications
• command lines

Note that the default bundle type is API.

Ok ! Let's do it !

gina bundle:add frontend @myproject

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.

Important: Since you are not running a local DNS Server, you have to change the host informations. Go to myproject/env.json & replace dev hostname from frontend-{env}-{scope}-v{projectVersionMajor}.{rootDomain} to localhost. This is a temporary hack and gina will soon be provided with its own local DNS Server.

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 for this particular bundle, let's say 8 GB:

gina bundle:start frontend @myproject --max-old-space-size=8192

Now, visit http://localhost:3100/ to check your homepage. Isn't it sexy !?

If you need to stop your bundle

gina bundle:stop frontend @myproject

If you need to restart your bundle

gina bundle:restart frontend @myproject

Adding templates

The default bundle renders a JSON representation of a "Hello World" message.

Let's add a view on our frontend

gina view:add frontend @myproject

Then restart your bundle

gina bundle:restart frontend @myproject

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.

Gina is shipped with Swig as the default template engine. If you are more comfortable with another template engine, you can use your own.

Setting your default environment

Please, note that you have 2 types of environments : one for the framework, and one for your project & your bundles.

By default, Gina (the framework) comes with 2 environments : dev and prod. The default is prod. If you are contributing to the framework or prototyping your application or service, we advise using the dev environment.

gina framework:set --env=dev

gina framework:set --log-level=debug

You can check which are the environments set for your projects

gina env:list

or for a particular project

gina env:list @myproject

NB.: When adding an environment, you will do so for the entire project.

Setting your application starting environment on runtime

This method does not memorize the selected environment as the default one for your application

You can have multiple environments for your project and decide to pick one as the starting env by using --env=<your_env> every time you have to run a bundle.

gina bundle:start frontend @myproject --env=prod

NB.: Omitting --env=<env> will fallback to your project default environment.

Setting your project or your application default environment

For the entire project & for all bundles inside by default

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.

Attention: Non-development env must be built before starting or restarting the bundle

gina project:build prod @myproject

Other operations you can apply to your environment

Adding a new environment for your project

gina env:add staging @myproject

Removing an existing environment for your project

gina env:rm staging @myproject

Defining an existing environment as development (you can only have one like this)

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
• /public
• /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:

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

You will get logs for the framework and related to your running bundles.

1st Method - The default one

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 --follow argument. E.g.: gina tail --follow

By default, Gina does not store logs. Logs are treated like any other events then printed out to the process.stdout.

This means that if you need Gina to handle logs storage, you need a logger container (or transport) to receive and output your logs.

Note that this is optional since logs are output like for other frameworks: you can catch those while writing your daemon starting script on your production server.

So to handle log storage for your application, you have 2 options: see 2nd & 3rd Methods.

2nd Method - Old school way

With this method, you will have to handle yourself log rotation

gina bundle:start frontend @myproject --log > /usr/local/var/log/gina/frontend.myproject.app.log 2>&1

You can now check

tail -f /usr/local/var/log/gina/frontend.myproject.app.log

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 developed a file container/transport that you just need to enable.

This feature is still experimental.

You can edit ~/.gina/user/extensions/logger/default/config.json to add "file" container to the flows.

You might need to restart gina :

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 development stage of your project, you might want to get all debug messages.

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 certificate for you, but you can use a service like SSL For Free to generate 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 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 at ~/.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 frontend.myproject.app folder should be placed into:

• ~/.gina/certificates/scopes/local for your dev host
• ~/.gina/certificates/scopes/production for your production host

Enable HTTPS scheme

NB.: certificate is required. By enabling HTTPS, you will do so for your entire project by default, but you can later set one per application. And if you want to run our experimental HTTP/2 implementation, you will need HTTPS scheme.

Check what is your actual scheme & protocol status

gina protocol:list @myproject

Setup HTTPS for the whole project

gina protocol:set @myproject

Setup HTTPS for a specific application

gina protocol:set frontend @myproject

Now, you just need to restart your bundle. You should tail your logs in order to get more details if an error is preventing you from starting.

gina tail

Open another terminal window

gina bundle:restart frontend @myproject

Depending on how you have managed to get your certificate for your dev environment, you might get this kind of message preventing your application to start :

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)

Do not panic, 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.

This is important and you will have to take additional steps to make your certificate fully valid while developing 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.

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 which you have then placed under: ~/.gina/certificates/scopes/local/frontend.myproject.app.

Step 1

Go to the folder

cd ~/.gina/certificates/scopes/local/frontend.myproject.app

List your files

ls

Output should look like

ca_bundle.crt   certificate.crt   private.key

Now, copy the content of certificate.crt

cat certificate.crt

Visit https://whatsmychaincert.com. 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/frontend.myproject.app).

Step 2

You now need to combine your private key with your new certificate. Still at ~/.gina/certificates/scopes/local/frontend.myproject.app ?

cat private.key certificate.chained+root.crt > certificate.combined.pem

To check:

openssl verify -CAfile certificate.combined.pem certificate.crt

Output should look like:

certificate.crt: OK

Final step

Go to your project src to add or edit your bundle config the following file : /path/to/myproject/src/frontend/config/settings.server.credentials.dev.json Where frontend is your bundle/application.

We just need to override Gina default certificate paths

{
    "ca": "{GINA_HOMEDIR}/certificates/scopes/{scope}/{host}/certificate.combined.pem"
}

Do this for all of your 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 certificate. If you have a wildcard certificate, you only need to follow the following steps once, then create a symlink for each bundle/service to the main certificate.

ln -s ~/.gina/certificates/scopes/local/myproject.app ~/.gina/certificates/scopes/local/frontend.myproject.app

Uninstalling Gina

For Microsoft Windows, you might have to run the command line with Administrator privileges.

Without prefix

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

npm uninstall -g gina --prefix=~/.npm-global

Troubleshooting

My settings are broken, I need a fresh install with the default settings

npm install -g gina@latest --reset

I can't start my bundle

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 framework root :

node node_modules/gina/script/pre_install.js -g

node node_modules/gina/script/post_install.js -g

Are you trying to restart after a crash ?

Before v0.1.0, Gina used 2 processes for each bundle: one master, one slave. Once an exception is thrown and the program crashes, one of the 2 processes can remain in the tasks/processes list.

Gina only uses one process per bundle or one per project if you have decided to merge bundles execution. This has been mostly observed for Windows users.

• If you are on a POSIX OS, you should look for gina, then kill it !

• If you are on Windows, look for node.exe or Event I/O Handler, then kill it !

After this, try again to start, it should run better.

More documentation and tutorials are coming soon !

For the full documentation, visit https://gina.io/docs/

License (MIT)

Copyright © 2009-2026 Rhinostone

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.