Deploying omnidb-server

Note: since the 3.6.x rewrite, omnidb-server is a single native binary (no separate webserver/websocket-server pair, no Django/CherryPy/Tornado) that answers every request itself over one port, using long-polling rather than websockets for background query/console/monitoring updates. There is also no configuration file or built-in TLS support anymore — everything is set via command-line flags, and any TLS termination must be handled by a reverse proxy in front of it.

Command options

Usage: omnidb-server [options]

Options:
  -A, --app              run in desktop app mode (always binds loopback-only,
                          regardless of -H)
  -H HOST, --host=HOST   listening address (default: 127.0.0.1)
  -p PORT, --port=PORT   listening port (default: an OS-chosen free port)
  -d HOMEDIR, --homedir=HOMEDIR
                         home directory containing the omnidb.db database and
                         the temp folder used for exported files

• -H specifies the address to listen on. Defaults to 127.0.0.1 (loopback-only) — pass 0.0.0.0 to accept connections from other machines, or a specific interface address.

• -p specifies the port to listen on, used in the browser’s URL when accessing OmniDB directly. If omitted, the OS picks a free port and prints it to stderr on startup.

• -d lets you choose the folder that stores omnidb.db (the application database) and the temp folder used for exported files. With this option it’s possible to run several instances of omnidb-server, each pointing at a different directory — handy for Docker deployments where you mount a volume there.

Security note: a server started with -H set to anything other than loopback should never also be started with -A/--app — the desktop auto-login link that mode generates is only meant to be reachable locally, so -A always forces loopback binding regardless of -H, ignoring it entirely rather than risk that combination.

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

Deploying OmniDB directly

Running omnidb-server with -H 0.0.0.0 (or a specific public interface) makes it directly reachable from other machines — but since there is no built-in TLS support, this means plain, unencrypted HTTP. This is not recommended for anything beyond a trusted local network: session cookies and query results would otherwise travel in the clear. For anything reachable from the wider internet, put a TLS-terminating reverse proxy (see below) in front instead of exposing omnidb-server directly.

Deploying OmniDB behind a reverse proxy

The recommended approach: run omnidb-server listening only on 127.0.0.1 (the default, so -H can be omitted) and let a reverse proxy such as Nginx or Caddy handle TLS termination and forward plain HTTP to it locally.

./omnidb-server -p 9000

Example Nginx configuration:

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 / {
        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;
    }
}

Since everything (including background query/console updates) is served over plain HTTP long-polling rather than websockets, a single location / block covering the whole app is all that’s needed — there’s no separate websocket upgrade path or /wss pattern to route specially anymore.