Runtime Configuration

The commons.jsonp file (located in bin/project/configs/) provides runtime configuration for the application. It chains through the dependency tree via extendsConfig, with each layer adding or overriding settings.

Configuration Chain

io-oidis-commons/bin/project/configs/commons.jsonp     ← Base defaults
    ← io-oidis-hub/bin/project/configs/commons.jsonp   ← Hub settings
        ← your-project/bin/project/configs/commons.jsonp ← Project overrides

Each level inherits from its parent. Your project config only needs to specify values that differ from the hub defaults.

Typical Project commons.jsonp

Io.Oidis.Builder.DAO.Resources.Data({
    extendsConfig: "dependencies/io-oidis-hub/bin/project/configs/commons.jsonp",

    database: {
        host: "localhost",
        port: 27018,
        name: "IoOidisIrmaDev"
    },

    auth: {
        sessionTimeout: 3600,
        maxLoginAttempts: 5
    },

    sendmail: {
        host: "smtp.example.com",
        port: 587,
        from: "noreply@example.com"
    },

    systemLog: {
        enabled: true,
        rotationDays: 90
    }
})

Common Configuration Sections

Section	Purpose	Detailed reference
`domain`	Server hostname, port, protocol, and TLS certificate paths	Hub Configuration — domain
`dbConfigs`	MongoDB connection — host, port, database name, credentials, auth source	Hub Configuration — dbConfigs
`authManagerWorker`	Session limits, login attempt tracking, 2FA enforcement, activation checks	Hub Configuration — authManagerWorker
`sendmail`	SMTP transport, sender address, admin list, queue interval, blacklist	Email System
`systemLog`	Audit log settings — enable, max age (days) for auto-cleanup	Hub Configuration — sysLog
`puppeteer`	Headless browser — Chrome build, threads, proxy, max wait time	Hub Configuration — puppeteer
`slack`	Slack bot token, display name, avatar icon	External Connectors
`msTeams`	Microsoft Teams incoming webhook URL, display name	External Connectors
`tunnels`	Agent tunneling — hub location, server hostnames, agent pool	Request Forwarding
`target`	Environment type, GA4 ID, PWA toggle, `preferDBSettings` flag	Application Settings

How Inheritance Works

The extendsConfig key creates a chain: each layer inherits all values from its parent and can override specific properties. The merge is deep — nested objects are merged recursively, not replaced.

// io-oidis-hub/bin/project/configs/commons.jsonp (parent)
Io.Oidis.Builder.DAO.Resources.Data({
    extendsConfig: "dependencies/io-oidis-commons/bin/project/configs/commons.jsonp",
    sendmail: {
        enabled: false,
        fetchTick: 10000,
        admins: []
    }
})

// your-project/bin/project/configs/commons.jsonp (child — your file)
Io.Oidis.Builder.DAO.Resources.Data({
    extendsConfig: "dependencies/io-oidis-hub/bin/project/configs/commons.jsonp",
    sendmail: {
        enabled: true,               // overrides hub default
        admins: ["admin@example.com"] // overrides empty array
        // fetchTick: 10000 — inherited from hub, no need to repeat
    }
})

tip

Only override what you need. The fewer values you declare, the easier it is to benefit from upstream improvements when the hub or commons defaults change.

Schema Validation

Each project can define a schema in package.conf.schema.jsonp that validates the commons.jsonp values at startup:

Io.Oidis.Builder.DAO.Resources.Data({
    extendsConfig: "dependencies/io-oidis-hub/bin/project/configs/package.conf.schema.jsonp",

    database: {
        port: { type: "number", required: true },
        name: { type: "string", required: true }
    }
})

Accessing Configuration at Runtime

Backend

The full merged configuration is available via the Loader singleton:

const config : IProject = Loader.getInstance().getAppConfiguration();

// Access specific sections
const dbName : string = config.dbConfigs.dev.dbName;
const mailEnabled : boolean = config.sendmail.enabled;
const envType : EnvironmentType = config.target.environmentType;

Frontend

The frontend only receives values whitelisted by embedFeatures. See Frontend Configuration for the full pipeline.

const config = this.getEnvironmentArgs().getProjectConfig();
const dbName = config.dbConfigs?.dbName;  // only if embedded

Runtime modification

Some settings can be changed at runtime through the Hub GUI without restarting the server. See Application Settings for the DB-backed settings bridge.

Configuration Chain​

Typical Project commons.jsonp​

Common Configuration Sections​

How Inheritance Works​

Schema Validation​

Accessing Configuration at Runtime​

Backend​

Frontend​

Runtime modification​