2. Installation

OmniDB provides 2 kinds of packages to fit every user needs:

  • OmniDB Application: Runs a web server on a random port behind, and provides a simplified web browser window to use OmniDB interface without any additional setup. Just feels like a desktop application.
  • OmniDB Server: Runs a web server on a random port, or a port specified by the user. User needs to connect to it through a web browser. Provides user management, ideal to be hosted on a server on users’ networks.

Both application and server can be installed on the same machine.

OmniDB Application

In order to run OmniDB app, you don’t need to install any additional piece of software. Just head to omnidb.org and download the latest package for your specific operating system and architecture:

  • Linux 64 bits
    • DEB installer
    • RPM installer
  • Windows 64 bits
    • EXE installer
  • Mac OSX
    • DMG installer

Use the specific installer for your Operational System and it will be available through your desktop environment application menu or via command line with omnidb-app.

https://raw.githubusercontent.com/OmniDB/doc/master/img/image_001.png

OmniDB Server

Like OmniDB app, OmniDB server doesn’t require any additional piece of software and the same options for operating system and architecture are provided.

Use the specific installer for your Operational System and it will be available through command line with omnidb-server:

user@machine:~$ omnidb-server
Starting OmniDB websocket...
Checking port availability...
Starting websocket server at port 25482.
Starting OmniDB server...
Checking port availability...
Starting server OmniDB 2.4.0 at 0.0.0.0:8000.
Starting migration of user database from version 0.0.0 to version 2.4.0
OmniDB successfully migrated user database from version 0.0.0 to version 2.4.0
Press Ctrl+C to exit

Note how OmniDB starts a websocket server in port 25482 and a web server in port 8000. You can also specify both ports and listening address:

user@machine:~$ omnidb-server -p 8080 -w 25000 -H 127.0.0.1
Starting OmniDB websocket...
Checking port availability...
Starting websocket server at port 25000.
Starting OmniDB server...
Checking port availability...
Starting server OmniDB 2.4.0 at 0.0.0.0:8080.
Starting migration of user database from version 0.0.0 to version 2.4.0
OmniDB successfully migrated user database from version 0.0.0 to version 2.4.0
Press Ctrl+C to exit

OmniDB with Oracle

OmniDB app and server does not require any piece of additional software, as explained above. But if you are going to connect to an Oracle database, then you need to download and install Oracle Instant Client (or extract it to a specific folder, depending on the operating system you use):

  • MacOSX: Download Oracle Instant Client (64-bit) and extract in ~/lib;
  • Linux: Download Oracle Instant Client (32-bit) (64-bit) and install it on your system, then set LD_LIBRARY_PATH;
  • Windows: Download Oracle Instant Client (32-bit) (64-bit) and extract it into OmniDB’s folder.

Note for Windows users using OmniDB app: For OmniDB 2.8 and above, you will need to extract Oracle Instant Client libraries inside of folder OMNIDBAPPINSTALLFOLDER\resources\app\omnidb-server.

OmniDB User Database

Since version 2.4.0, upon initialization both server and app will create a file ~/.omnidb/omnidb-app/omnidb.db (for OmniDB app) or ~/.omnidb/omnidb-server/omnidb.db (for OmniDB server) in the user home directory, if it does not exist. That can be confirmed by the message OmniDB successfully migrated user database from version 0.0.0 to version 2.4.0 you saw above. This file is also called user database and contains user data. If it already exists, then OmniDB will check whether the version of the server matches the version of the user database:

user@machine:~$ omnidb-server
Starting OmniDB websocket...
Checking port availability...
Starting websocket server at port 25482.
Starting OmniDB server...
Checking port availability...
Starting server OmniDB 2.4.0 at 0.0.0.0:8000.
User database version 2.4.0 is already matching server version.
Press Ctrl+C to exit

Future releases of OmniDB will contain the user database migration SQL commands required to upgrade the user database, if necessary. This way user data is not lost by upgrading OmniDB. Imagine the following scenario: you use OmniDB 2.4.0 now and you decide to upgrade it to newest release 2.5.0, for example. After the upgrade, when you start OmniDB server, it will apply the changes version 2.5.0 requires. So you will see something like that:

user@machine:~$ omnidb-server
Starting OmniDB websocket...
Checking port availability...
Starting websocket server at port 25482.
Starting OmniDB server...
Checking port availability...
Starting server OmniDB 2.5.0 at 0.0.0.0:8000.
Starting migration of user database from version 2.4.0 to version 2.5.0
OmniDB successfully migrated user database from version 2.4.0 to version 2.5.0
Press Ctrl+C to exit

OmniDB configuration file

Starting on version 2.1.0, OmniDB server comes with a configuration file omnidb.conf that enables the user to specify parameters such as port and listening address. Also, 2.1.0 enables us to start the server with SSL, this requires a certificate and is configured in the same configuration file. For more details about how to deploy the OmniDB server, please read Chapter 19.

Starting on version 2.4.0, this file is located in ~/.omnidb/omnidb-server/omnidb.conf in the user home directory.

OmniDB in the browser

Now that the web server is running, you may access OmniDB browser-based app on your favorite browser. Type in address bar: localhost:8000 and hit Enter. If everything went fine, you shall see a page like this:

https://raw.githubusercontent.com/OmniDB/doc/master/img/image_002.png

Now you know that OmniDB is running correctly. In the next chapters, we will see how to login for the first time, how to create an user and to utilize OmniDB.