Advanced Configuration: Configuration File Reference

TGateway configuration is by default located in the GatewayApp/Configuration/ directory. At startup, appsettings.json is loaded, then merged with the JSON configuration under Configuration/; In production deployment, parameters such as port, database, JWT key (the signing key for login tokens), and log retention policies should be prioritized through configuration files or environment variables.

Configuration files and directories

First, look at the terminology

Configuration File List

Project data directory

ProjectDirectory is a gateway startup setting in appsettings.json in the program directory. An empty value uses the program directory for project data. Relative paths are resolved against the program directory. Restart the gateway after changing this setting.

{
  "ProjectDirectory": "D:/GatewayProjects/LineA",
  "ConfigurationScanDirectories": ["Configuration"]
}

The ProjectDirectory environment variable can override the file setting. The command-line option --ProjectDirectory D:/GatewayProjects/LineA can override it as well. Precedence is the base settings file, the current environment settings file, environment variables, then command-line arguments. The project directory must contain its required appsettings.json and Configuration/ files. Studio prepares these files and supplies the startup setting for each project.

DOTNET_ENVIRONMENT selects the environment; --environment EnvironmentName takes precedence over that environment variable. Scanned project configuration files also remain below environment variables and command-line arguments in priority. A gateway managed by Watchdog uses its on-site GatewayApp directory. A directory from another machine carried in a project package does not change the on-site data location.

Project configuration, DB/, OTHERDB/, logs, PluginCache/, scripts, custom nodes, plugin history databases, user resources, and OPC UA certificates use the project directory. Program DLLs, the bundled compiler, and program dependencies remain in the program directory. Automatically generated OPC UA client application certificates are stored in the project’s opc/pki/own; applications with the same name in different projects receive independent certificates.

For example, with ProjectDirectory set to D:/GatewayProjects/LineA, database settings are read from D:/GatewayProjects/LineA/Configuration/Database.json, and Web settings from that project’s Configuration/WebApiOptions.json. Other projects read their own files with the same names. The program directory’s Configuration/ is not shared business configuration. Edit the target project’s files and restart that project.

Multiple projects can share the same program files while using separate project directories and Web ports. Plan additional protocol ports, external databases, explicitly configured absolute paths, and device connections separately. The project directory setting does not rewrite external resources.

Default data directories

Web access and authentication

WebApiOptions

WebApiOptions.json Used to set listening ports and allowed access sources for TGateway Web/API.

modify Port and restart TGateway. When deploying under Watchdog, you also need to synchronously confirm the Gateway API port configuration in Watchdog.

JWTOptions

Production environments must replace the default Secret. Enter a strong key directly, or use $ENVIRONMENT_VARIABLE_NAME or ${ENVIRONMENT_VARIABLE_NAME} to read it from an environment variable. When using an environment variable, confirm that it is set before starting TGateway. Do not keep using the sample key in production, because different deployments would share the same signing key and weaken token security.

ExternalIdentity

Identity providers, secrets, public site address, default roles, and login policy are stored in the current administration realm. Maintain them in System Management → Identity Authentication. Follow Identity Authentication and Single Sign-On to save a draft, check connectivity, complete a real login test, and publish.

ExternalIdentityHostOptions in ExternalIdentity.json declares host entry points only:

Register the complete protocol callback displayed on the provider page. Do not register the frontend callback page as the platform protocol endpoint. After changing the public URL, update Site Address and recheck platform registration and login.

Storage and logs

Database

Database.json configured for business and log database connections. By default, SQLite is deployed, but you can also switch to other databases as required by the site.

B y default, SQLite connects strings explicitly enable WAL log mode to enhance runtime read-write concurrency. When migrating, backing up, or copying SQLite files, attention should be paid to both the main database file and any possible running -wal, -shm files; Before switching to another database, back up the original database and confirm that the target database account, network, firewall, and initialization permissions are available.

LoggerOptions

LoggerOptions.json Includes process file logs, gateway business logs, backend management logs, and ASP.NET log level configuration.

GatewayLogOptions Used to control gate business log retention policies such as acquisition, rules, forwarding, and RPC:

AdminLogOptions for controlling backend management, operations, SQL, and audit log retention policies:

The Logging node controls ASP.NET, console, and Windows Event Log levels. By default, Default, Microsoft, and Microsoft.Hosting.Lifetime are set to Warning. Temporarily lower the level when diagnosing framework-level issues, then restore it to avoid excessive logging.

Runtime settings

ChannelThread

Channel, device, and variable limits are no longer read from ChannelThread: the free tier is fixed at 50 channels, 50 devices, and 1000 variables. Once exceeded, the signed limits in the local offline license determine the available capacity. Hardware resources can still impose lower practical limits.

IdGeneratorOptions

The ID generator uses the snowflake algorithm. Common fields are as follows:

WorkerIdBitLength + SeqBitLength cannot exceed 22. For multi-node deployments, assign each node a WorkerId before starting the services. Do not allow two nodes writing to the same data set to use the same WorkerId.

SeedDataOptions

After the production system has defined user, role, menu, or button permissions, the database should be backed up before modifying the forced refresh option. When restoring the system’s built-in menu or button, only the corresponding item can be enabled to avoid affecting on-site users and role configurations.

Related Links

• System Settings - Runtime Settings in Web Pages
• Quick Start - Default Ports and Boot Order
• Watchdog Web Operation Manual - Watchdog Terminal Gateway API port configuration