Skip to content
Platform > Dynamic Components

How Dynamic Components Work

A 3forge Enterprise deployment's component set is defined in the file data/ami.components, which AmiCore watches and reloads while running. This page describes the file format, the component types, and how a change to the file becomes a change to the running estate.

Overview

data/ami.components is the record of which components AmiCore runs. Each non-blank, non-comment line declares one component. AmiCore reads the file on startup, starts every component it lists, and then polls the file on an interval so that later edits take effect without a restart.

A change reaches the running estate in 2 ways: an edit to the file, which the poll detects, or a call on the ami admin console object, which applies the change and writes it back to the file. Both converge on the same result, and the file is always the persisted record.

The components file

Each line uses the form name;type;pwd:

  • name: a unique name for the component. The running component is named ami_<name>.
  • type: the component type, one of the component types below. The value is read case-insensitively.
  • pwd: the working directory for the component. A single period (.) means the AmiCore process working directory.

A shipped file looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# AMI Components State File
# Each non-blank, non-comment line declares one component:
#   name;type;pwd
#     name - unique component name
#     type - CENTER | RELAY | WEB | WEBBALANCER | WEBMANAGER
#     pwd  - working directory (use . for the process default)
#
# Example:
#   relay;RELAY;.
#   center;CENTER;.
#   web;WEB;.
#
relay;RELAY;.
center;CENTER;.
web;WEB;.

Fields are separated by semicolons, and a backslash escapes a literal semicolon. Whitespace around a line or a field is ignored. A line beginning with # is a comment, and blank lines and comments are preserved when the file is rewritten.

Component types

A component is one of the following types:

  • CENTER: the realtime and historical database and event-processing engine.
  • RELAY: the data-virtualization and feed-handling layer.
  • WEB: the browser application server.
  • WEBBALANCER: the load-balanced front door that distributes live user sessions.
  • WEBMANAGER: the centralized store of user profiles and dashboards.
  • GATEWAY: the governed distribution layer for external clients.

Note

The file generated on first boot lists the first 5 types in its header comment and omits GATEWAY. GATEWAY is a valid type and can be added to the file like any other.

How a change is applied

AmiCore polls data/ami.components every 5 seconds by default and reconciles the running components with the file:

  • A line added to the file starts that component.
  • A line removed from the file stops and deregisters that component.
  • A changed line stops the old component and starts the replacement.

Components already running are left untouched, so a change to one component does not restart the others. The poll interval is configurable, and polling can be turned off entirely. See Configuration.

An unusable entry stops AmiCore from starting

A reload and a startup treat a broken entry differently. While AmiCore is running, an entry it cannot start affects only that component. At startup, the same entry is fatal to the whole process: AmiCore logs Shuting down due to fatal error on startup with the underlying cause, and exits with code 3 before any component starts.

A line whose working directory does not exist fails this way, with Missing directory: <pwd>. Because the file persists across restarts, an edit that looks harmless on a running system can prevent the next start. Check the components file before restarting, and see Troubleshooting.

What persists, and what does not

A change made through the admin console is written back to data/ami.components only when it changes the set of components:

  • Adding a component and removing a component are written to the file, so they survive a restart.
  • Starting, stopping, restarting, and reloading an existing component are not written to the file. These act on a component that is already declared, and the file already reflects it.

A component added by editing the file is already recorded by definition, so the reconcile does not rewrite the file for it.

Note

When a component is added through the admin console, its working directory is recorded in data/ami.components as a resolved absolute path. A component added by editing the file keeps the value as written, so a period (.) stays a period. A console-added line and a hand-written line for the same component can differ in the pwd field while describing the same component.

Transient components

A transient component is a short-lived copy of an existing component that is never written to data/ami.components. Cloning a component as transient creates a copy under the transient directory, in a delete_me subdirectory named <source>_transient<N>, on an unused port from a configured range. The copy is not restored on the next restart. Transient components suit throwaway tasks, such as a temporary second instance for a test. See Configuration for the transient directory, retention, and port-range properties.