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.