Hub Configuration Reference

Hub extends the localhost IProject interface with additional configuration sections for authentication, email, webhooks, agents, external services, and more. All settings are defined in commons.jsonp and optionally overridden per environment.

Source: Interfaces/IProject.ts

Configuration Sections

domain

Extends localhost IServerConfigurationDomain.

Property	Type	Purpose
localhostName	string	Internal hostname for the localhost server

Plus all parent properties: hostname, port, protocol, cert, key, etc.

dbConfigs

Database connection settings. Supports separate configurations for development, production, and PostgreSQL.

Property	Type	Purpose
dev	IDbConfiguration	Development database connection
prod	IDbConfiguration	Production database connection
postgres	IDbConfiguration	PostgreSQL alternative connection

Each IDbConfiguration:

Property	Type	Purpose
location	string	Database host/IP
port	number	Database port
dbName	string	Database name (inherited from parent)
user	string	Authentication username
pass	string	Authentication password
protocol	string	Connection protocol (e.g. mongodb, mongodb+srv)
attributes	string	Connection string attributes
authSource	string	Authentication database
fileStorageLocation	string	Path for file-based storage

authManagerWorker

Authentication background worker configuration.

Property	Type	Purpose
enabled	boolean	Enable the cron worker thread for auth maintenance tasks
activationCheck.enabled	boolean	Enable periodic user activation/expiration checks
activationCheck.interval	number	Check interval in seconds
cleanUpService.enabled	boolean	Enable expired reset token cleanup
cleanUpService.interval	number	Cleanup interval in seconds
singInCheck.enabled	boolean	Enable login attempt tracking
singInCheck.numberOfTries	number	Max failed login attempts before lockout
singInCheck.interval	number	Lockout check interval in seconds
multiSessionEnabled	boolean	Allow multiple concurrent sessions per user
strictEmailCheck	boolean	Enforce strict email validation (duplicate checking)
strictSecureSSOcookies	boolean	Enforce Secure flag on SSO cookies (requires HTTPS)
twoFactorAuthentication.force	boolean	Require 2FA for all users
twoFactorAuthentication.identityName	string	TOTP issuer name (shown in authenticator apps)

sendmail

Email engine configuration. Type: ISendmailConfiguration (from hub-gui).

Key properties include SMTP server settings, sender address, domain, fetch tick interval, admin email list, and blacklist. See Email System for usage details.

Property	Type	Purpose
enabled	boolean	Enable email sending
domain	string	Application domain for email links (falls back to server hostname)
fetchTick	number	Queue processing interval in milliseconds
admins	string[]	Admin email addresses for system notifications
blackList	string[]	Email addresses excluded from all sends
defaultSender	string	Default sender address
batchSize	number	Max queued records delivered per loop tick (default 50)
maxQueueAgeHours	number	Queued records older than this are dead-lettered instead of sent (default 48)
maxSendAttempts	number	Failed sends are auto-retried up to this many attempts before dead-letter (default 5)
retryBackoffSec	number[]	Delay in seconds before the n-th retry; the last value repeats (default [60, 300, 900, 3600])

Plus SMTP transport configuration (host, port, auth, TLS).

slack

Slack integration configuration.

Property	Type	Purpose
enabled	boolean	Enable Slack notifications
token	string	Slack Bot OAuth token (xoxb-...)
icon	string	Bot avatar image URL
name	string	Bot display name

msTeams

Microsoft Teams integration configuration.

Property	Type	Purpose
enabled	boolean	Enable MS Teams notifications
webhookURL	string	Incoming webhook URL
name	string	Display name prepended to messages

tunnels

Agent tunneling configuration for the reverse proxy system.

Property	Type	Purpose
hubLocation	string	Public URL of this Hub instance (used by agents to connect)
server	string[]	Hostname aliases that trigger tunnel routing (domain → agent forwarding)
agent	string[]	Agent pool identifiers

See Request Forwarding for architecture details.

certs

TLS certificate management. Extends localhost ICertsConfiguration.

Property	Type	Purpose
whitelist	string[]	Domains allowed for certificate generation

Plus parent properties: certPath, keyPath, etc.

deploy

Deployment notification settings.

Property	Type	Purpose
slackChannel	string	Slack channel for deployment notifications

agentsRegisterUser

Service account credentials for agent registration.

Property	Type	Purpose
user	string	Service account username
pass	string	Service account password

warning

If agentsRegisterUser.user is empty, the agent service initialization is skipped entirely.

target

Application target settings. Extends localhost IProjectTarget.

Property	Type	Purpose
environmentType	EnvironmentType	Environment classification (e.g. DEVELOPMENT, PRODUCTION)
ga4ID	string	Google Analytics 4 measurement ID
initPageEnabled	boolean	Enable the first-time initialization page
pwaEnabled	boolean	Enable Progressive Web App features
preferDBSettings	boolean	Prefer AppSettings from DB over config file values
colorSchemeSupported	boolean	The theme of the target renders both a light and a dark appearance, so "My profile" may offer the color scheme choice. Default false

// bin/project/configs/commons.jsonp
target: {
    colorSchemeSupported: true
}

With colorSchemeSupported: false (the default) the Hub MyProfilePanel does not render the "Color scheme" section at all and BasePageLayoutController does not touch the Bootstrap color mode — a theme without a dark appearance keeps looking the way it is designed. Turn it on only for a theme that carries a dark variant; the choice is then stored per user account, see Extending Hub GUI.

note

The flag is read in the browser, so it has to reach the client config through target.embedFeatures. The Hub adds project.target.colorSchemeSupported to its hubFeatures group; a project that replaces that whole group has to list the key again.

sysLog

System audit log configuration.

Property	Type	Purpose
enabled	boolean	Enable database-backed audit logging
maxAge	number	Days to keep log entries (older entries auto-deleted)

puppeteer

PDF generation and headless browser configuration.

Property	Type	Purpose
enabled	boolean	Enable Puppeteer PDF generation
urlThreads	number	Number of concurrent browser pages
maxWaitTime	number	Maximum render wait time in milliseconds
proxy.enabled	boolean	Enable proxy for browser requests
proxy.location	string	Proxy server URL
chromeBuildId	string	Specific Chrome/Chromium build to use
cacheDir	string	Chrome binary cache directory

When enabled, PDF initialization is awaited during the Hub's onDbPrepared startup hook. The configured Chrome build must already be present in cacheDir, or the process must be able to download it. In an isolated test image, prepopulate that cache during image construction, or set puppeteer.enabled: false when PDF output is outside the scenario. A failed browser installation rejects super.onDbPrepared() and can prevent a solution's subsequent startup hooks, including its cron registration, from running.

apiConfig

API rate limiting configuration.

Property	Type	Purpose
maxPrintRequests	number	Maximum concurrent print requests
maxIdsPerPrintRequests	number	Maximum IDs per single print request

webhooks

Webhook processing loop configuration.

Property	Type	Purpose
enabled	boolean	Enable webhook processing
tick	number	Processing interval in milliseconds
bucketSize	number	Maximum records per processing batch

See Webhooks for details.

oidishook

Hub-to-hub synchronization configuration.

Property	Type	Purpose
enabled	boolean	Enable OidisHook adapter
server.hostname	string	Remote Hub URL
server.userName	string	Authentication username
server.token	string	Authentication token
bidirectionalSync	boolean	Enable two-way synchronization
strongValidation	boolean	Strictly validate webhook source

authProviders

OAuth2 provider configuration.

Property	Type	Purpose
google.enabled	boolean	Enable Google OAuth2
google.authUri	string	Google authorization endpoint
google.tokenUri	string	Google token endpoint
google.scope	string[]	OAuth2 scopes to request
google.projectId	string	Google Cloud project ID
google.clientId	string	OAuth2 client ID
google.clientSecret	string	OAuth2 client secret
google.redirectUri	string	OAuth2 redirect URI
google.reloadUrl	string	URL to redirect after authentication

Top-Level Flags

Property	Type	Purpose
noReport	boolean	Disable crash reporting (Sentry)
forceAgentsAuthorization	boolean	Require explicit authorization for all agent connections

Deprecated

Property	Status	Migration
defaultUser	Deprecated	Use the Hub GUI admin initialization page instead. The Loader automatically marks and deletes legacy default users on startup

---

See also: Configuration Overview | Commons Config | Hub Backend Overview