Platform > Operations

Configuration Files¶

This page describes the configuration files 3forge Enterprise reads, how to override shipped settings, and how the runtime validates them.

Overview¶

Configuration lives in the config/ directory beneath the installation root. The runtime ships a complete set of defaults and expects your changes to sit in a separate override file, so that an upgrade can replace the defaults without discarding your configuration.

The runtime also checks the shipped defaults file against the version it was built with, and reports any difference at startup.

Configuration files¶

File	Purpose
`config/defaults.properties`	Every property the runtime reads, with its shipped default. Do not edit
`config/local.properties`	Your overrides. Edit this file
`config/root.properties`	Bootstrap properties
`config/speedlogger.properties`	Logger configuration
`config/3fsecurity.properties`	Java security properties

The configuration directory is set by property.f1.conf.dir, which the startup script passes as config/.

Overriding a property¶

Add the property to config/local.properties. Where the property holds a list and you want to extend rather than replace it, reference the existing value:

ami.datasource.plugins=$${ami.datasource.plugins},PLUGINNAME

Without the reference, your value replaces the shipped list entirely and the default plugins stop loading.

Put each property on its own line, and each comment on a line of its own. A # starts a comment only at the beginning of a line, so text after a value on the same line becomes part of the value:

# Correct: the comment is on its own line
ami.log.stats.otel.max.retries=2

ami.log.stats.otel.max.retries=2   # Wrong: the value read is "2   # Wrong: ..."

Warning

Do not edit config/defaults.properties. The runtime compares it against the version it was built with and reports every difference at startup. Your edits will be flagged as drift, and an upgrade will overwrite them.

Defaults validation¶

At startup the runtime compares the shipped defaults.properties against an expected copy embedded in the runtime library, and prints a line-by-line difference for any mismatch. The behavior is controlled by a system property passed on the command line:

Value	Behavior
`WARN`	Log the difference and continue
`EXIT`	Log the difference and stop
`SKIP`	Do not check

The startup script sets WARN. EXIT is the behavior when the property is absent entirely, so a hand-built command line without it will refuse to start on any drift.

To change it, edit the -Dvalidate.default.properties value in scripts/start.sh.

Selected properties¶

ami.components.file

Default:

1	`ami.components.file=data/ami.components`

Description:

The file listing which components this instance runs.

ami.plugins.dir

Default:

1	`ami.plugins.dir=./plugins`

Description:

The directory scanned for plugin bundles at startup.
Created by the startup script if absent.

ami.global.dir

Default:

1	`ami.global.dir=.`

Description:

The root against which keystore and public key paths resolve.

users.access.file

Default:

1	`users.access.file=./data/access.txt`

Description:

The file defining users when the access file authenticator is in use.

exit.on.missing.users.access.file

Default:

1	`exit.on.missing.users.access.file=true`

Description:

Whether the process stops when the access file is absent.
Leaving this enabled prevents an instance starting with no users defined.

Properties requiring installed plugins¶

Several shipped defaults name capabilities that are not included in the distribution. They must be installed as plugins before the default becomes meaningful:

Property	Requires
`ami.web.panel.plugins=*`	A wildcard over whatever panel plugin bundles are installed. The Mapbox panel plugin bundle must be installed for a Maps panel to work, but the property itself needs no edit: install the bundle and the wildcard picks it up
`ami.font.files=./data/fonts/*.ttf`	Font files placed in `data/fonts/`

The font directory is not populated by the distribution, so anything depending on bundled fonts requires the fonts to be supplied.