Downloading and Starting the App

Zingoolarity is available as so-called "release bundles".

Release bundles are TAR files, which (when untarred) produce a directory called "zingoolarity" containing the source files, the compiled executable, the configuration file and a couple of supplementary directories (containing icons and other assets).

Having a look at the README.txt file in the "zingoolarity" directory contains more information.

Before you start the Zingoolarity executable, you need to setup a MariaDB or MySQL database, which will be used to store your data.

This can be a local MariaDB or MySQL engine or a remote SaaS offering.

Assuming you have a local engine installation, open your command line, become "root" (with e.g. "sudo bash") and start the "mysql" command line client.

Then enter the following SQL engine commands:

create database zingoolarity;
use zingoolarity;
create user 'melaniebush'@'localhost' identified by 'Test123!';
grant all privileges on zingoolarity.* to 'melaniebush'@'localhost';
flush privileges;

The example user "melaniebush", the database name "zingoolarity" and (naturally) the password can be changed to something different for your own installation.

They need to be matched by the entries in your "zingoolarity.ini" configuration file.

Open "zingoolarity.ini" with your favorite text editor and make the necessary changes.

Now start Zingoolarity interactively by entering:

./zingoolarity

You will receive some startup messages and everything should be fine.

A typical error at this point is that the default web server port 8080 is already in use on your computer.

If this is the case, make the necessary changes in the "zingoolarity.ini" file.

Now open your favorite web browser and enter the following URL:

http://localhost:8080/ascabera

This is the default database initialization URL configured in the "zingoolarity.ini" file (the default is named after a magic spell from a video game).

Click on "yes" and Zingoolarity will automatically create the necessary tables and indexes in your newly created database.

Be careful if you already have data in your Zingoolarity tables.
Everything will be deleted!

Now check the command line.
There should be some error messages related to "drop table" statements.
These messages are perfectly normal during the first run against an empty database, as Zingoolarity tries to drop the tables before creating them and in an empty database they do not exist yet. If you receive any other error message, check it carefully.
It usually means that you cannot connect to your database or you do not have granted the necessary access rights (as described further above).
Correct the error by either editing the "zingoolarity.ini" file and adapting the database configuration parameters or grant the necessary rights in the mysql command line client.

Very important final step:
Now stop the running Zingoolarity process by pressing CTRL-C, open the "zingoolarity.ini" file with your favorite text editor and search for the "initactive" configuration parameter.
Uncomment it and set it to false.
This disables the database initialization URL we used above.
If you miss this step, everybody who knows the database initialization URL of your installation can invoke it and thereby delete your entire data by recreating the database!
Spare you this grief by following above instructions!

Another important note about security for production use:
Either proxy your Zingoolarity service with a web proxy (e.g. Apache of Nginx) with a valid SSL certificate+key or obtain a valid SSL certificate+key (e.g. from Lets Encrypt) and configure it correctly in your "zingoolarity.ini" file.
Your production URL should begin with https://.
Do not use http:// (unencrypted) for production installations, as traffic can easily be intercepted and secret information (e.g. personal secret certificates) can be obtained!

Now you can start using Zingoolarity from your web browser.

Setting Up Different Realms

Zingoolarity optionally allows you to setup different so-called "realms".

The default realm is called "zingoolarity".

A realm is basically a completely separate and isolated database with its own Zingoolarity data objects.

It allows you to run for example different unrelated companies on the same Zingoolarity instance.

Realms are implemented as different logical databases in the same MariaDB or MySQL engine process.

If you for example want to setup a separate realm for testing and training, you simply repeat the "create database" steps which have already been explained in the previous chapter:

create database zingtest;
use zingtest;
grant all privileges on zingtest.* to 'melaniebush'@'localhost';
flush privileges;

Note that Zingoolarity realms must all run in the same MariaDB or MySQL engine process and have the same connection parameters (parameters "dbserver", "dbport", "dbusername" and "dbpassword" in the "zingoolarity.ini" configuration file).

The only thing that differs is the "dbname".

To enable switching to your new realm, you have to add its name to the "dbrealms" parameter in the zingoolarity.ini configuration file (and restart your Zingoolarity instance):

dbrealms = |zingoolarity||zingtest|

This is for security purposes, so that only intended databases can be used.

You can now enter the new realm name into the login screen and click "Login".

Zingoolarity will try to connect to the database, which will take longer than usual as the database is not yet initialized and errors will be logged to the console.

But Zingoolarity will switch to the new realm anyhow.

You can now initialize your new database by visiting the database initialization URL.

"Realms" are an advanced feature of Zingoolarity.

If you only want to start, you do not have to consider them and stay with the default realm called "zingoolarity".

Adding a brand icon

You may have noticed that, after switching to your new realm, there is a "broken" icon in the top level menu bar, right next to the Zingoolarity menu icon.

This is because Zingoolarity tries to render a "brand" icon as soon as it does not run the default "zingoolarity" realm.

Just place a ".png" image file with a logo in the "/asset" directory inside of the Zingoolarity directory, which is named like

[realm].png

This will be automatically picked up after the next browser action in Zingoolarity.

Here is an example:

(A brand icon for a separate realm)

Other options to run multiple companies

Naturally, you can also run a separate Zingoolarity process on a different web port and a different database.

This requires creating an additional ".ini" file (a copy-and-modify of "zingoolarity.ini") and specifying the new configuration file at the command line when invoking Zingoolarity:

./zingoolarity zingtest.ini

With this approach you have the full flexibility.

You can use databases on the same or on different MariaDB or MySQL processes with the same or different user credentials and connection parameters.

This approach should also be chosen to better scale for large installations.

Using the Cloud SaaS Option

The authors of Zingoolarity run a cloud instance of the latest Zingoolarity release at the domain zingoolarity.com.

It can be reached by the following URL:

https://www.zingoolarity.com

This instance is usually not available for public usage and a basic authentication is required for a public HTTPS connection.

If you are somehow associated with the authors of Zingoolarity and your expected computing load requirements are moderate, you can ask for the setup of a separate realm on this instance.

This spares you the operating of your own instance.

This is not a commercial service; it is provided by a "best effort" approach and only available in limited cases.