Deploying the Data Gateway

This article covers prerequisites and steps for deploying a Data Gateway.

Prerequisites

Before configuring your first Data Gateway, please note the following requirements:

1. Lumi admin access to the Lumi AI platform

   • Creating a Data Gateway instance requires admin-level privileges.

2. A host machine running Windows or Linux (or a Linux container — see Docker Deployment below)

3. Network access for the host machine to the source system/database

4. Outbound HTTPS (port 443) access from the host machine to the Internet

   • Required for connecting to the Lumi AI platform. See Network Configuration for specific IP addresses and hostname requirements.

5. Microsoft ODBC Driver 18 for SQL Server installed on the host — if connecting to SQL Server

   • Required only for SQL Server connections. All other supported engines have their drivers bundled in the gateway executable. Download from Microsoft's documentation. The Docker image includes this driver pre-installed.

Running the Data Gateway

To run, you define the configuration/identity for the Data Gateway instance, download the application, and start it.

1. Define a Data Gateway Instance in the Lumi AI Platform Settings Panel​

Use the Data Gateway tab of the Admin Settings page to create a new Data Gateway. Provide a name (and optionally a description) for easy identification.

A token will be generated for use in configuring and authenticating the gateway. Keep this token securely — you will need it in the next steps.

The token is displayed only once for security. If it is lost or compromised, you can generate a new one from the same panel.

In most cases, a single Data Gateway instance can serve multiple source systems, provided those systems are all accessible from the same host. Create multiple instances only if your source systems span isolated networks (e.g., separate regional environments with no shared connectivity).

2. Download the Data Gateway

The Data Gateway is distributed as a single standalone executable — no runtime or additional dependencies need to be installed separately (except the SQL Server ODBC driver noted above). Download the latest version for your platform from the Data Gateway tab of the Admin Settings page.

Place the executable in a dedicated directory on the host (e.g., /opt/lumi-gateway on Linux, or C:\lumi-gateway on Windows). The gateway locates its config.yaml and writes its logs folder relative to the executable's own location, so a stable, dedicated directory makes managing these files straightforward.

On Linux, mark the file as executable after downloading: chmod +x <lumi-data-gateway-filename>

Keep the Data Gateway up to date to benefit from the latest features and fixes. The Admin Settings panel will indicate if your running instance is outdated.

3. Apply a Configuration

The gateway is configured via a config.yaml file placed in the same directory as the executable. At minimum, only the token field is required.

# Lumi AI Data Gateway Configuration

token: "<your gateway token>"

# Optional settings (defaults shown):
# service_endpoint: https://api.lumi-ai.com   # Lumi AI platform endpoint
# console_log_level: INFO                      # Log verbosity for console output
#                                              # Valid values: TRACE, DEBUG, INFO,
#                                              #   SUCCESS, WARNING, ERROR, CRITICAL
# retry_count: 5                               # Max consecutive connection failures
#                                              #   before the gateway gives up
# reset_time: 300                              # Seconds before the retry counter resets

Configuration can also be supplied via environment variables or command-line arguments, which take precedence over the config file in that order:

Setting	config.yaml key	Environment variable	CLI flag
Token	token	LUMI_AI_DATA_GATEWAY_TOKEN	--token
Platform endpoint	service_endpoint	LUMI_AI_DATA_GATEWAY_SERVICE_ENDPOINT	--service-endpoint
Console log level	console_log_level	LUMI_AI_DATA_GATEWAY_CONSOLE_LOG_LEVEL	--console-log-level
Retry count	retry_count	LUMI_AI_DATA_GATEWAY_RETRY_COUNT	--retry-count
Reset time	reset_time	LUMI_AI_DATA_GATEWAY_RESET_TIME	--reset-time

4. Start the Data Gateway

Run the executable from its directory. The gateway runs in the foreground and prints log output to the terminal.

Linux

./lumi-agent-linux-vX.X.XX

Windows (Command Prompt or PowerShell)

.\lumi-agent-windows-vX.X.XX.exe

To run the gateway as a background service that starts automatically at boot, see Configuring the Data Gateway for Boot.

If any issues arise, see Troubleshooting below.

5. Check the Admin Panel

The Data Gateway instance should now appear as Active in the Admin Settings panel.

An Active status confirms the gateway process is running and connected to the platform. It does not validate the connection configuration for a specific Knowledge Base — you can test and verify source system connectivity from the Knowledge Base settings.

6. [Optional] Configure the Data Gateway to Run at Startup

See Configuring the Data Gateway for Boot for instructions on setting up the gateway as a service or scheduled task on Linux or Windows.

Docker Deployment

A Linux Docker image is available for enterprise customers on request. Contact support to obtain the image.

The Docker image is based on Ubuntu 22.04 and includes:

• The gateway binary at /opt/lumi-ai-data-gateway/lumi-ai-data-gateway

• Microsoft ODBC Driver 18 for SQL Server (pre-installed — no extra setup needed for SQL Server connections)

• A non-root lumi user for runtime security

No inbound ports are exposed. The gateway communicates outbound only.

Running with Docker

The simplest way to run is to pass the token as an environment variable:

docker run -d \
  --name lumi-data-gateway \
  --restart unless-stopped \
  -e LUMI_AI_DATA_GATEWAY_TOKEN= \
  <image>

To persist logs on the host, mount the logs directory:

docker run -d \
  --name lumi-data-gateway \
  --restart unless-stopped \
  -e LUMI_AI_DATA_GATEWAY_TOKEN=<your-token> \
  -v /opt/lumi-gateway/logs:/opt/lumi-ai-data-gateway/logs \
  <image>

To use a config.yaml file instead of environment variables, mount it into the container at the expected path:

docker run -d \
  --name lumi-data-gateway \
  --restart unless-stopped \
  -v /opt/lumi-gateway/config.yaml:/opt/lumi-ai-data-gateway/config.yaml:ro \
  -v /opt/lumi-gateway/logs:/opt/lumi-ai-data-gateway/logs \
  <image>

Running with Docker Compose

services:
  lumi-data-gateway:
    image: <image>
    container_name: lumi-data-gateway
    restart: unless-stopped
    environment:
      - LUMI_AI_DATA_GATEWAY_TOKEN=<your-token>
    volumes:
      - ./logs:/opt/lumi-ai-data-gateway/logs

Save this as docker-compose.yml and run:

docker compose up -d

Viewing Logs

Container stdout (console output at INFO level):

docker logs lumi-data-gateway
docker logs -f lumi-data-gateway # follow

If you mounted the log volume, the full DEBUG-level log file is at the host path you specified.

Checking Health

The image includes a health check that confirms the gateway process is running:

docker inspect --format='{{.State.Health.Status}}' lumi-data-gateway

A status of healthy means the process is running. Check the Admin Settings panel to confirm the gateway is connected to the platform.

The Docker image is Linux-only. For Windows hosts, use the standalone executable with the Task Scheduler or Windows Service method described in Configuring the Data Gateway for Boot.

Troubleshooting

Check the admin panel status

If the instance shows as Inactive, verify the process is running on the host and restart it if necessary.

Check the gateway log

The logs folder next to the executable (or the mounted volume path for Docker) contains up to 7 days of logs at DEBUG level. Error events are logged with context that can help identify the root cause.

Verify the token

If the token is invalid or associated with a different gateway instance, the gateway will not connect. Generate a new token from the Admin Settings panel and update your configuration.

Verify outbound network connectivity

The gateway host must be able to reach Lumi AI's endpoints over HTTPS on port 443. Test basic connectivity from the host:

# Linux / macOS
curl -I https://api.lumi-ai.com
curl -I https://broker.lumi-ai.com

# Windows (PowerShell)
Invoke-WebRequest -Uri https://api.lumi-ai.com -Method Head
Invoke-WebRequest -Uri https://broker.lumi-ai.com -Method Head

Any response (including an error status code) confirms the TCP connection is working. A connection timeout or TLS error points to a firewall or SSL inspection issue — see Network Configuration for guidance.

If none of the above resolves the issue, contact Lumi AI support.