Configuration

Central knobs that shape every build: paths, defaults, validation, RBAC, limits, timeouts. All of them live in src/com/qa/config/QAConfig.groovy and the majority can be overridden via Jenkins global environment variables without changing code.

Where to set globals

Manage Jenkins → System → Global properties → Environment variables. Adding or changing a variable there takes effect on the next build — no Jenkins restart required.

Overrides applied via Jenkins env vars:

QA_MASTER_SHARED_LIB, QA_MASTER_ENVS_DIR, QA_MASTER_SERVICES_DIR, QA_MASTER_META_DIR, QA_MASTER_SCHEMAS_DIR, QA_MASTER_BACKUPS_DIR, QA_MASTER_EXPORTS_DIR, QA_MASTER_ENV_TEMPLATES_DIR, QA_MASTER_SNAPSHOTS_DIR, QA_AGENT_ENVS_DIR
QA_DEFAULT_RUNNER, QA_DEFAULT_TTL, QA_DEFAULT_DATABASE
QA_RBAC_ENABLED, QA_ADMIN_USERS, QA_ADMIN_GROUP
QA_MAX_ENVS_PER_USER, QA_MAX_ENVS_PER_AGENT, QA_MAX_SERVICES_PER_ENV, QA_MAX_OWNERS_PER_ENV, QA_MAX_DISK_MB
QA_DEPLOYMENT_TIMEOUT, QA_HEALTH_CHECK_TIMEOUT
QA_LOG_VERBOSE (see Logging DSL)
HARBOR_URL, HARBOR_CREDENTIAL_ID

QAConfig.Paths.AGENT_ENVS_DIR defaults to /opt/qa-envs — not the /home/jenkins/agent/qa-envs value mentioned in some older notes. If your agents already have envs under the old path, set QA_AGENT_ENVS_DIR=/home/jenkins/agent/qa-envs to keep them working.

QAConfig reference

Table 1. `QAConfig.Paths`
Field	Default	Env override
`MASTER_SHARED_LIB`	`/var/jenkins_home/qa-data/shared-lib`	`QA_MASTER_SHARED_LIB`
`MASTER_ENVS_DIR`	`/var/jenkins_home/qa-data/envs`	`QA_MASTER_ENVS_DIR`
`MASTER_SERVICES_DIR`	`${MASTER_SHARED_LIB}/resources/services`	`QA_MASTER_SERVICES_DIR`
`MASTER_META_DIR`	`/var/jenkins_home/qa-data/meta`	`QA_MASTER_META_DIR`
`MASTER_SCHEMAS_DIR`	`${MASTER_SHARED_LIB}/resources/schemas`	`QA_MASTER_SCHEMAS_DIR`
`MASTER_BACKUPS_DIR`	`${MASTER_ENVS_DIR}/.backups`	`QA_MASTER_BACKUPS_DIR`
`MASTER_EXPORTS_DIR`	`${MASTER_SHARED_LIB}/exports`	`QA_MASTER_EXPORTS_DIR`
`MASTER_ENV_TEMPLATES_DIR`	`${MASTER_SHARED_LIB}/env-templates`	`QA_MASTER_ENV_TEMPLATES_DIR`
`MASTER_OPERATION_LOG`	`${MASTER_ENVS_DIR}/.operation-log.ndjson`	(derived)
`MASTER_AUDIT_LOG`	`${MASTER_ENVS_DIR}/.audit-log.ndjson`	(derived)
`MASTER_SNAPSHOTS_DIR`	`${MASTER_ENVS_DIR}/.snapshots`	`QA_MASTER_SNAPSHOTS_DIR`
`AGENT_ENVS_DIR`	`/opt/qa-envs`	`QA_AGENT_ENVS_DIR`
`DEPENDENCIES_YAML`	`${MASTER_SHARED_LIB}/resources/schemas/dependencies.yaml`	(derived)
`TEMPLATES_DIR`	`${MASTER_SHARED_LIB}/resources/templates`	(derived; legacy)

Table 2. `QAConfig.Status` / `QAConfig.TTL`
`Status.CONFIGURED / DEPLOYED / STOPPED / FAILED / UNKNOWN`	String constants used for `meta.status`.
`TTL.ONE_DAY / THREE_DAYS / ONE_WEEK / ONE_MONTH / TWO_MONTHS / THREE_MONTHS / ONE_YEAR / INFINITY`	Allowed values for `meta.ttl`; `TTL.isValid(s)` / `TTL.ALL` available.

Table 3. `QAConfig.Defaults`
Field	Default	Env override
`RUNNER`	`built-in`	`QA_DEFAULT_RUNNER`
`TTL`	`infinity`	`QA_DEFAULT_TTL`
`DATABASE_TYPE`	`mysql`	`QA_DEFAULT_DATABASE`
`NETWORK_NAME_SUFFIX`	`_net`	(compile-time)

Table 4. `QAConfig.Registry`
Field	Default	Env override
`HARBOR_URL`	`hub.friendly-tech.com`	`HARBOR_URL`
`HARBOR_CREDENTIAL_ID`	`harbor-cred`	`HARBOR_CREDENTIAL_ID`

Table 5. `QAConfig.Validation`
`ENV_NAME_PATTERN`	`^[a-z0-9][a-z0-9-]{2,49}$` — 3–50 chars, lowercase letters / digits / hyphen. May start with a digit (commit `83b82f9`).
`ENV_NAME_MIN_LENGTH` / `ENV_NAME_MAX_LENGTH`	`3` / `50`.
`MAX_NAME_GENERATION_ATTEMPTS`	`15`.
`RESERVED_NAMES`	`master, main, test, default, prod, null, built-in, all, temp, tmp, none`.
`PORT_MIN` / `PORT_MAX`	`1024` / `65535`.
`PASSWORD_MIN_LENGTH`	`8`.
`SENSITIVE_PATTERN`	`(?i).(PASSWORD\|SECRET\|TOKEN\|_KEY\|API_KEY\|CREDENTIAL).` — drives `isSensitiveVariable` and `maskSensitiveValues`.

Table 6. `QAConfig.Limits`
Field	Default	Env override
`MAX_ENVS_PER_USER`	`5`	`QA_MAX_ENVS_PER_USER`
`MAX_ENVS_PER_AGENT`	`10`	`QA_MAX_ENVS_PER_AGENT`
`MAX_SERVICES_PER_ENV`	`20`	`QA_MAX_SERVICES_PER_ENV`
`MAX_OWNERS_PER_ENV`	`5`	`QA_MAX_OWNERS_PER_ENV`
`MAX_DISK_MB`	`51200` (50 GiB)	`QA_MAX_DISK_MB`

Table 7. `QAConfig.RBAC`
Field	Default	Env override
`ENABLED`	`true`	`QA_RBAC_ENABLED`
`ADMIN_USERS`	`[admin]`	`QA_ADMIN_USERS` (comma-separated)
`ADMIN_GROUP`	`qa-admins`	`QA_ADMIN_GROUP`

Table 8. `QAConfig.Timeouts` (seconds)
Field	Default	Env override
`DEPLOYMENT`	`600`	`QA_DEPLOYMENT_TIMEOUT`
`HEALTH_CHECK`	`300`	`QA_HEALTH_CHECK_TIMEOUT`
`CONTAINER_STARTUP`	`10`	(compile-time)
`PORT_CHECK`	`5`	(compile-time)

Environment variable precedence

The resolver in utils.substituteVariables walks binding sources in this order — the first match wins:

Service-specific file: resources/services/<service>/.env or .env.<db>.
Global file: resources/services/.env.<db>.
Template default inside the Compose block: ${VAR:-default}.

See Variable Substitution for edge cases (:- vs :?, escaping, nested substitution).

`meta.json` at a glance

Persisted per env under MASTER_ENVS_DIR/<env>/meta.json. Rewritten atomically by utils.atomicWriteMeta. Full schema and field-level notes are in lifecycle.

Registry authentication

Private registry: Harbor at {HARBOR_URL} (default hub.friendly-tech.com).
Credential ID: {HARBOR_CREDENTIAL_ID} (default harbor-cred) — Jenkins username/password credential used by docker login and tag-listing API calls.
Tag listing has an embedded fallback credential inside createEnvStep.groovy to survive short Harbor outages during parameter render; the actual deploy always uses the Jenkins credential.

Agent selection (Deploy-Environment)

No label requirement. Any online agent other than master / built-in is eligible.
meta.runner is re-proposed as the default on subsequent deploys.
Offline agents are filtered out of the dropdown; choosing one is not possible through the UI.

ft-qoe-web — layered `.env`

Since the layered .env refactor (commit 908c88f), application-level variables for ft-qoe-web live in resources/services/ft-qoe-web/.env under their native, unprefixed names (SERVER_PORT, MAIL_HOST, FTACS_IP_ADDRESS, …) exactly as Spring Boot reads them. A small set of host-side tunables stays in the root .env.<db> under the FT_QOE_WEB_ prefix to avoid port collisions between co-located stacks (commit 7ac5f73).

Host port / JVM mappings — root `.env.<db>`

Variable Default Description

Variable	Default	Description
`FT_QOE_WEB_PORT`	`8085`	Host port for the main listener. HTTP when SSL is off, HTTPS when on.
`FT_QOE_WEB_HTTP_PORT`	`8087`	Host port for the plain-HTTP fallback, relevant only when `SERVER_SSL_ENABLED=true`.
`FT_QOE_WEB_DEBUG_PORT`	`5005`	Host port for JDWP. The mapping line is commented out by default — uncomment to enable.
`FT_QOE_WEB_JAVA_RAM`	`-Xms512m -Xmx2g`	Optional JVM heap override injected into `JAVA_OPTS`.

FT_QOE_WEB_PORT

8085

Host port for the main listener. HTTP when SSL is off, HTTPS when on.

FT_QOE_WEB_HTTP_PORT

8087

Host port for the plain-HTTP fallback, relevant only when SERVER_SSL_ENABLED=true.

FT_QOE_WEB_DEBUG_PORT

5005

Host port for JDWP. The mapping line is commented out by default — uncomment to enable.

FT_QOE_WEB_JAVA_RAM

-Xms512m -Xmx2g

Optional JVM heap override injected into JAVA_OPTS.

Application variables — `resources/services/ft-qoe-web/.env`

Variable Default Description

Variable	Default	Description
`SPRING_PROFILES_ACTIVE`	`mysql`	Spring profile; selects DB dialect.
`SERVER_PORT`	`8085`	Container listener port.
`HTTP_PORT`	`8087`	Secondary plain-HTTP port inside the container (SSL-only).
`SERVER_SSL_ENABLED`	`false`	Enable HTTPS on `SERVER_PORT`.
`DB_MAX_POOL_SIZE`	`10`	HikariCP — max pool size.
`DB_MIN_IDLE`	`5`	HikariCP — min idle.
`DB_CONNECTION_TIMEOUT_MS`	`30000`	HikariCP — timeout waiting for a free connection (ms).
`DB_IDLE_TIMEOUT_MS`	`600000`	HikariCP — idle retirement (ms).
`DB_MAX_LIFETIME_MS`	`1800000`	HikariCP — max lifetime per connection (ms).
`QUARTZ_DB_USERNAME`	`ftacs_quartz`	DB user for the Quartz schema.
`UI_DB_USERNAME`	`ftacs_qoe_ui`	DB user for the QoE UI schema.
`FTACS_IP_ADDRESS`	`ftacs`	Hostname of the ACS for API calls (matches the Compose service name).
`CACHE_CONFIG_PATH`	`file:/etc/app/cache/`	Hazelcast client config dir inside the container.
`DM_ISP_MODE`	`2`	ISP display mode (`0` disabled, `1` subscriber, `2` ACS).
`MAIL_HOST` / `MAIL_PORT` / `MAIL_USERNAME` / `MAIL_PASSWORD`	(empty) / `587` / (empty) / (empty)	SMTP settings — commented out by default.
`SERVER_SSL_KEY_STORE` (and friends)	(empty)	PKCS12 keystore / truststore paths and passwords.

SPRING_PROFILES_ACTIVE

mysql

Spring profile; selects DB dialect.

SERVER_PORT

8085

Container listener port.

HTTP_PORT

8087

Secondary plain-HTTP port inside the container (SSL-only).

SERVER_SSL_ENABLED

false

Enable HTTPS on SERVER_PORT.

DB_MAX_POOL_SIZE

10

HikariCP — max pool size.

DB_MIN_IDLE

5

HikariCP — min idle.

DB_CONNECTION_TIMEOUT_MS

30000

HikariCP — timeout waiting for a free connection (ms).

DB_IDLE_TIMEOUT_MS

600000

HikariCP — idle retirement (ms).

DB_MAX_LIFETIME_MS

1800000

HikariCP — max lifetime per connection (ms).

QUARTZ_DB_USERNAME

ftacs_quartz

DB user for the Quartz schema.

UI_DB_USERNAME

ftacs_qoe_ui

DB user for the QoE UI schema.

FTACS_IP_ADDRESS

ftacs

Hostname of the ACS for API calls (matches the Compose service name).

CACHE_CONFIG_PATH

file:/etc/app/cache/

Hazelcast client config dir inside the container.

DM_ISP_MODE

2

ISP display mode (0 disabled, 1 subscriber, 2 ACS).

MAIL_HOST / MAIL_PORT / MAIL_USERNAME / MAIL_PASSWORD

(empty) / 587 / (empty) / (empty)

SMTP settings — commented out by default.

SERVER_SSL_KEY_STORE (and friends)

(empty)

PKCS12 keystore / truststore paths and passwords.

The historical FT_QOE_WEB_MAIL_*, FT_QOE_WEB_SERVER_SSL_*, and FT_QOE_WEB_ACS_HOST variables no longer exist anywhere in the codebase since the per-service .env split. Any documentation or pipeline still referencing them should be updated to the native names above.

ClickHouse connection

CLICKHOUSE_DB_URL is not part of the per-service .env. Compose assembles it for ft-qoe-web out of the shared CLICKHOUSE_HOST, CLICKHOUSE_HTTP_PORT and CLICKHOUSE_DATABASE, and appends socket_timeout=120000 so a stalled ClickHouse cannot pin the connection indefinitely.

the URL resolves the HTTP port (CLICKHOUSE_HTTP_PORT, default 8123), not the native TCP one (CLICKHOUSE_PORT, default 9000). ft-qoe-web replaced the retired com.github.housepower native JDBC driver with the official com.clickhouse one, which speaks HTTP; ftacs reads the same variable after making that move earlier. Both ports stay published by the clickhouse service, so pointing the URL back at 9000 fails at connect time rather than being ignored (DEV-2736).