19. Deploying omnidb-server

Whenever deploying omnidb-server the user must be aware of how OmniDB works in terms of ports so the environment can be properly configured taking the infrastructure into account.

OmniDB uses 2 servers to answer user requests, one is the default webserver serving the application itself and the other is a websocket server used by several parts of OmniDB, such as Query, Console and Debugging Tab, allowing a bi-directional communication between the client and the server which enhances performance and user experience. This means that 2 ports need to be properly configured:

Both servers support SSL so OmniDB can run by itself securely without the need of a load balancer or reverse proxy, such as Nginx.

The configuration of ports and certificates can be done via command options or configuration file.

Command options

Usage: omnidb-server [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -H HOST, --host=HOST  listening address
  -p PORT, --port=PORT  listening port
  -w WSPORT, --wsport=WSPORT
                        websocket port
  -e EWSPORT, --ewsport=EWSPORT
                        external websocket port
  -d HOMEDIR, --homedir=HOMEDIR
                        home directory containing local databases config and
                        log files
  -c CONF, --configfile=CONF
                        configuration file

Configuration File

The configuration file, omnidb.conf by default, can be used to set all the parameters specified in the previous category and a few additional parameter related to SSL and some about the query server itself.

This file is created when OmniDB is started for the first time or when a new folder is specified with the option -d. If no folder is specified the default location for files is:

Here is the default configuration file:

# OmniDB Server configuration file

[webserver]

# What address the webserver listens to, 0.0.0.0 listens to all addresses bound to the machine
listening_address    = 127.0.0.1

# Webserver port, if port is in use another random port will be selected
listening_port       = 8000

# Websocket port, if port is in use another random port will be selected
websocket_port       = 25482

# External Websocket port, use this parameter if OmniDB isn't directly visible by the client
# external_websocket_port = 25482

# Security parameters
# is_ssl = True requires ssl_certificate_file and ssl_key_file parameters
# This is highly recommended to protect information
is_ssl               = False
ssl_certificate_file = /path/to/cert_file
ssl_key_file         = /path/to/key_file

# Trusted origins, use this parameter if OmniDB is configured with SSL and is being accessed by another domain
csrf_trusted_origins = origin1,origin2,origin3

[queryserver]

#Max number of threads that can used by each advanced object search request
thread_pool_max_workers = 2

#Number of seconds between each prompt password request. Default: 30 minutes
pwd_timeout_total = 1800

Let's take a look on how to deploy omnidb-server in different scenarios:

Deploying OmniDB directly

In this case no load balancers or reverse proxies are used, OmniDB is accessed directly and is extremely recommended to start it with SSL enabled if it will be visible to the outside world.

For this scenario the user needs to specify the following parameters:

It is important to mention here that both ports need to visible to every client trying to access OmniDB.

Deploying OmniDB behind a reverse proxy

In this case OmniDB won't be accessed directly but through a properly configured load balancer or reverse proxy.

For this scenario a possible approach is to run omnidb-server listening to the local address 127.0.0.1 and without SSL, given that the balancer will handle the security part.

The following parameters are required:

Consider this example of OmniDB being hosted behind Nginx:

omnidb-server -H 127.0.0.1 -p 9000 -w 26500 -e 443

In this case OmniDB can only be accessed locally and the browser will try to connect to the websocket server with the default https port (443).

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    include snippets/ssl-domain.conf;
    include snippets/ssl-params.conf;
    server_name domain.org;
    client_max_body_size 75M;

    location /wss {
        proxy_pass http://127.0.0.1:26500;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Ssl https;
        proxy_set_header   X-Forwarded-Proto https;
        proxy_set_header   X-Forwarded-Port 443;
        proxy_set_header   Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Ssl https;
        proxy_set_header   X-Forwarded-Proto https;
        proxy_set_header   X-Forwarded-Port 443;
        proxy_set_header   Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

As can be seen, Nginx is listening for requests to domain.org in port 443. Since we also specified the external websocket port to 443, websocket requests will be dealt here too.

Websocket requests are always directed to the pattern /wss so we use a specific location configuration to redirect all requests to the port specified with -w, 26500 in this case.

Other requests that are not to /wss should all be redirected to OmniDB server, 9000 in this case.