Installation¶

This section describes how to install XLTable, configure system access and connect analytical databases.

XLTable can be deployed on Linux or Windows servers and supports integration with Active Directory and multiple databases.

Linux¶

XLTable can be installed on modern Linux distributions. Ubuntu 22.04+ is recommended for production environments.

Prerequisites¶

Ubuntu 22.04+ server with sudo access
Network access to analytical databases
Open ports 80 or 443 for Excel clients
XLTable distribution zip placed in /usr/olap/ (e.g. xltable-1.0.0-ubuntu.zip)

Prepare system¶

Create working directory:

sudo mkdir /usr/olap
sudo chmod a+rwx /usr/olap

Install XLTable¶

Copy XLTable distribution zip to the server:

scp xltable-*-ubuntu.zip user@server:/usr/olap/

Run the install script:

bash install_xltable.sh

The script will:

Install supervisor, nginx, unzip
Extract xltable to /usr/olap/xltable/
Create /usr/olap/xltable/setting/settings.json from the example (if missing)
Configure supervisor to autostart the service
Configure nginx as a reverse proxy on port 80

Set up connections with database (configuration examples in the folder /usr/olap/xltable/setting):

nano /usr/olap/xltable/setting/settings.json

Example of a minimal settings.json:

{
  "SERVER_DB": "ClickHouse",
  "CREDENTIAL_DB": {
      "user": "...",
      "password": "...",
      "host": "...",
      "port": "8443",
      "secure": "True"
  },
  "WRITE_LOG": false,
  "OWNERS": {"admin": "pass1"},
  "USERS": {"name": "password"},
  "USER_GROUPS": {"name": ["group_name"]},
  "MAX_ROWS": 100000,
  "LDAP_CACHE_TIMEOUT": 300,
  "CONVERT_FIELDS_TO_STRING": true,
  "CREDENTIAL_ACTIVE_DIRECTORY": {
      "server_address": "..",
      "domain": "..",
      "domain_full": "..",
      "username": "..",
      "password": "..",
      "access_group": ".."
     }
 }

Note

After each change to the settings.json file, restart the service:

sudo supervisorctl restart olap

Upgrading version¶

Copy the new distribution zip to the server (remove or replace any previous zip first):

scp xltable-*-ubuntu.zip user@server:/usr/olap/

Run the update script:

bash update_xltable.sh

The script will:

Verify the zip integrity
Back up settings.json and .lic license files
Replace the xltable installation
Restore the backed-up config and license files
Reload supervisor

Service Management¶

Action	Command
Start	`sudo supervisorctl start olap`
Stop	`sudo supervisorctl stop olap`
Restart	`sudo supervisorctl restart olap`
Status	`sudo supervisorctl status olap`
Logs	`sudo tail -f /var/log/supervisor/olap*.log`

Windows¶

XLTable can be installed on Windows Server. Windows Server 2019+ is recommended for production environments.

Prerequisites¶

Windows Server 2019+ with administrator privileges
Network access to analytical databases
Open ports 80 or 443 for Excel clients

Prepare system¶

Install IIS (Web Server role).
Install URL Rewrite and ARR (Application Request Routing).
Create working directory: c:\olap

Install XLTable¶

Copy XLTable distribution file into the working directory and unpacking it. Set up connections with database (configuration examples in the folder c:\olap\xltable\setting):

Configure the IIS site as a reverse proxy on the local port http://127.0.0.1:5000/{R:0} and add the REMOTE_USER header to the request.

Installing the service XLTable using NSSM (Non-Sucking Service Manager):

nssm install XLTable "C:\olap\xltable\main.exe"
nssm start XLTable

Enable required authentication in IIS.

Note

After each change to the settings.json file, restart the service:

nssm restart XLTable

Authentication¶

XLTable supports two authorization modes: local authentication defined in settings.json and integration with Active Directory(LDAP).

Local authorization¶

At the basic level, authorization is configured directly in the settings.json file.

Administrators can define:

Users and passwords
User groups
Mapping of users to groups

This mode is suitable for: - test environments - small installations - isolated deployments without domain infrastructure

Example structure:

"USERS": {"user1": "pass1", "user2": "pass2"},
"USER_GROUPS": {"user1": ["olap_users"], "user2": ["olap_admins"]},

Active Directory integration¶

XLTable supports authentication and authorization using Microsoft Active Directory.

Active Directory integration allows you to: - Authenticate users automatically - Map AD users and groups to XLTable roles - Centralize access management

To enable Active Directory authentication, configure the corresponding section in the settings.json file.

This section defines connection parameters to the domain controller, account for looking up user information, group mapping rules and other LDAP parameters.

Example structure:

"CREDENTIAL_ACTIVE_DIRECTORY": {
    "server_address": "dc.company.org",
    "domain": "company",
    "domain_full": "company.org",
    "username": "service_olap",
    "password": "...",
    "access_groups": ["olap_users_all", "olap_users_sales", "olap_users_accounting"]
}

Admin panel¶

XLTable includes a built-in admin panel for monitoring and managing the server.

URL¶

The admin panel is available at:

http://<server>/admin

Access is protected by a separate set of credentials defined in OWNERS (independent from regular USERS).

Configure admin credentials¶

Add the OWNERS section to settings.json:

"OWNERS": {"admin": "secret_password"}

Note

OWNERS credentials are completely separate from USERS. A user defined in USERS cannot access the admin panel, and an owner cannot connect as a regular Excel user.

Features¶

The admin panel provides:

Service status — confirms the server is running and shows the active database backend.
Documentation — direct link to the XLTable documentation.
Clear Cache — removes all cached session data. Users will need to re-authenticate after the cache is cleared.

Database connections¶

XLTable connects directly to analytical databases and executes SQL queries on their side. All database connections are defined centrally in the settings.json file and reused across OLAP cubes.

Currently supported connection types:

ClickHouse
BigQuery
Snowflake
Trino

For each database type, the corresponding configuration section must be defined in settings.json.

ClickHouse¶

Example structure for ClickHouse connection:

"SERVER_DB": "ClickHouse",
 "CREDENTIAL_DB": {
     "user": "...",
     "password": "...",
     "host": "...",
     "port": "8443",
     "secure": "True"
 },

BigQuery¶

Example structure for BigQuery connection with path to service account key file:

"SERVER_DB": "BigQuery",
"CREDENTIAL_DB": {
    "key_path": "..."
},

Snowflake¶

Example structure for Snowflake connection:

"SERVER_DB": "Snowflake",
"CREDENTIAL_DB": {
     "user": "...",
     "password": "...",
     "account": "...",
     "warehouse": "...",
     "schema": "..."
},

Trino¶

Example structure for Trino connection:

"SERVER_DB": "Trino",
"CREDENTIAL_DB": {
    "host": "...",
    "port": 8443,
    "user": "...",
    "password": "...",
    "catalog": "...",
    "http_scheme": "https",
    "verify": false
},

StarRocks¶

Example structure for StarRocks connection:

"SERVER_DB": "StarRocks",
"CREDENTIAL_DB": {
    "host": "...",
    "port": ...,
    "user": "...",
    "password": "...",
},