Configuration

Three configuration files are relevant, when we're talking about Fleet Manager:

1. The installer's configuration file: fminstaller.appsettings.json
2. The FM CLI configuration file: fm.appsettings.json
3. Fleet Manager's configuration file: appsettings.json

We'll walk through them one by one here. 🙂 Fleet Manager can also pick up

4. Configuration from environment variables

which is useful if you intend to host it in a Docker container.

1. The installer's configuration file

When you have run the installer the first time with a command the required the presence of a license, the installer will have added the license document to its configuration file, which is residing just next to the installer:

/fm-installer.exe
/fminstaller.appsettings.json

Its contents look somewhat like this:

{
  "license": {
    "Document": {
      "Id": "1111112222233333coffeebada551111",
      "Licensee": {
        "Name": "Your Comnay Name",
        "Vat": "CC3847892748392-343"
      },
      "IssuedOn": "20190523"
    },
    "Signature": "nv754m5840mvh5frfrg95049586949yh8954y8549j=="
  }
}

(possibly including an Expiry field at the same level as IssuedOn, if the license you have is a TRIAL license).

When the installer needs to download new Fleet Manager binaries, it will use the license to acquire a token, which it will then use to download the necessary files.

The installer will also automatically inject the license into Fleet Manager's configuration, when running the configuration wizard.

2. The FM CLI configuration file

When the installer wizard has configured a Fleet Manager installation, it will have injected appropriate settings into the CLI configuration file, which is residing in the cli subdirectory of your Fleet Manager installation:

/cli/fm.exe
/cli/fm.appsettings.json

The CLI configuration file has the following layout:

{
  "environments": {
    "local": {
      "key": "eyJ0eXAiOiJKV1Q(long key)fiyvbyFw",
      "ui": "http://MHG-PC:11011/ui",
      "api": "http://MHG-PC:11011/api"
    }
  }
}

which means that this particular CLI is configured with knowledge of one single Fleet Manager installation, local, which it will try to reach using the configured URLs and access key.

3. Fleet Manager's configuration file

The configuration file is residing next to FleetManager.WebApp.exe, which is the main executable.

/FleetManager.WebApp.exe
/appsettings.json
/(...) 100s of other files

Here's an example, including comments:

{
  "AppSettings": {
    // master encryption key - used to generate all tokens and keys in Fleet Manager
    "masterkey": "OJcmF(..long key..)Gnj/USQ==",
    // configures where log output should go - MUST include a file name
    "logpath": "c:\\logs\\fm\\log.txt",
    // configures a filter for the minimum level that log output must have to be included in the log file
    "loglevel": "Information",
    // configures SMTP settings
    "smtp": {
      // set to a) a hostname of an SMTP server, or b) a directory path of a local email pickup directory
      "host": "c:\\data\\fm\\emails",
      "port": 25,
      // optional: configures SMTP login credentials
      "user": "",
      "pass": "",
      // optional: specifies whether TLS should be enabled
      "tlsenabled": true,
      // optional: configures the sender address used when sending emails
      "sender": "[email protected]",
      // optional: configures whether accounts should optimize message retries by default
      "optimizeMessageRetriesByDefault": "false"
    },
    // configures which URL Fleet Manager should listen on
    "listenUrl": "http://MHG-PC:11011",
    // if the URL above is HTTPS, you must point to a .PFX file with a server certificate
    "certPath": "",
    // optionally providing a password, if one was used during the export
    "certPass": "",
    // configures the URL which Fleet Manager can be accessed on from the outside
    "url": "http://MHG-PC:11011",
    // configures where the API is running (will almost always be the value of the previous setting with /api appended)
    "apiUrl": "http://MHG-PC:11011/api",
    // configures the topic used for ingesting events
    "kafkatopic": "fmevents",
    // the license document provided to you by Rebus FM
    "license": {
      "Document": {
        "Id": "utu483tu8493u8794758439758493789",
        "Licensee": {
          "Name": "Your Company Name",
          "Vat": "CC-48398235t74tm74"
        },
        "IssuedOn": "20190523"
        // if your license is a TRIAL license, it'll have the "Expiry" field as well
        // , "Expiry": "20200101"
      },
      "Signature": "4mt85n85ny5m74m5hm5hg758hg758h4g785h47ghhy=="
    },
    // when the "events" connection string is for Kafka, you may configure SASL_SSL key/secret here
    "confluentCloudKey": "",
    "confluentCloudSecret": "",
    // ⚠️ADVANCED⚠️ Overrides the topic used for ingesting events on the producer side, which can be useful in migration scenarios
    "kafkatopicproduceroverride": "",
  },
  "ConnectionStrings": {
    // Configures persistence for ingested events
    // 1) Kafka URL, 2) File system directory (single-process installations only!), 3) Azure Storage Account connection string (single-process installations only!)
    "events": "c:\\data\\fm\\events",

    // Configures persistence for master data
    // 1) MongoDB connection string, 2) MSSQL connection string, 3) PostgreSQL connection string
    "master": "mongodb://localhost/fm-local-master",

    // Configures persistence for persistent projections
    // 1) MongoDB connection string, 2) File system directory (via LiteDB), 3) PostgreSQL connection string
    "views": "mongodb://localhost/fm-local-views",

    // Configures persistence for server-sent commands to Rebus instances
    // 1) MongoDB connection string, 2) File system directory, 3) MSSQL connection string, 4) PostgreSQL connection string
    "commands": "mongodb://localhost/fm-local-commands",

    // Configures persistence for "blob" data
    // 1) Azure Storage Account connection string, 2) File system directory, 3) Amazon S3 connection string(*1)
    "viewblobs": "c:\\data\\fm\\blobs",

    // Configures queueing system to use for internal communication
    // 1) Azure Service Bus connection string, 2) File system directory, 3) Amazon SQS connection string(*1)
    "servicebus": "c:\\data\\fm\\bus",

    // ⚠️ADVANCED⚠️ Advanced feature! Overrides persistence for ingested events on the producer side, which can be useful in migration scenarios
    // 1) Kafka URL, 2) File system directory (single-process installations only!), 3) Azure Storage Account connection string (single-process installations only!)
    "eventsProducerOverride": "c:\\data\\fm\\events",
  },

  // optional section that configures the installation to accept Azure AD-based auth
  "AzureAd": {
    // tenant ID and client ID must match those in your app registration
    "TenantId": "f57829ae-c213-4ca4-9063-84e071394dd2",
    "ClientId": "b2e93f5b-5c86-43c4-8cfb-9a2476395a09",

    // the domain must match the ending of your email addresses, so e.g. to accept "[email protected]" you'd write this:
    "Domain": "my-domain-name.com",

    // if you have additional users (e.g. guest users) in your AD, you can add them here:
    "AdditionalEmails": "[email protected]; [email protected]",

    // optional element: indicates group IDs that should be automatically treated as member/admin roles on all teams
    "Roles": {
      // users that belong to this group will automatically become members of all teams
      "MemberGroupId": "2acf0c81-47b9-4fb2-9ea7-df44fefd7d78",
      // users that belong to this group will automatically become admins of all teams
      "AdminGroupId": "f50fbf9f-797f-4b55-92ea-ca1eb4bdcbc7"

      // users that do NOT belong to either group will be DENIED access to all teams
    }
  } 

}

4. Configuring Fleet Manager with environment variables

All of the keys present in Fleet Manager's configuration file have correponding environment variables prefixed with FM_ (F M underscore) and __ (two underscores) used for nesting (casing insensitive).

E.g. to configure the events database connection string with an environment variable, set the variable FM_CONNECTIONSTRINGS__EVENTS to a value. Or, to set the SMTP host, use the environment variable FM_APPSETTINGS__SMTP__HOST.

Special note about the license

Just to be entirely clear about this, because the license part is nested deeper than the other settings: To configure the license using environment variables, you'll need to provide the following settings:

FM_APPSETTINGS__LICENSE__DOCUMENT__ID
FM_APPSETTINGS__LICENSE__DOCUMENT__LICENSEE__NAME
FM_APPSETTINGS__LICENSE__DOCUMENT__LICENSEE__VAT
FM_APPSETTINGS__LICENSE__DOCUMENT__ISSUEDON
FM_APPSETTINGS__LICENSE__SIGNATURE

(possibly including FM_APPSETTINGS__LICENSE__DOCUMENT__EXPIRY, if your license is a TRIAL license)

5. Footnotes

(*1): Amazon connection strings are expected to configure basic AWS credentials by specifying ;-separated key-value pairs with the necessary values. For S3, AccessKey, SecretKey, Region, and BucketName must be provided. For SQS, AccessKey, SecretKey, and Region must be provided.