Configuration Management

Overview

FusionAuth is a key part of your application infrastructure. How can you manage changes to the configuration? How can you promote changes from one environment to another?

Configuration Management Options

There are a number of options you can use to manage the configuration of your FusionAuth instance over time, as well as to promote changes from one environment (such as staging) to another (such as production).

Script The Changes

You can script your changes using the API and apply those scripts to different environments. You can either use the API directly or a client library in one of the supported programming languages.

This approach is similar to database migration scripts except the scripts make REST calls against the FusionAuth API instead of SQL calls against a database. The scripts are run during upgrades of an application or as a standalone project that other applications depend upon.

If you are using an application framework such as rails, you can leverage the existing migration framework.

Using this approach gives you full access to the FusionAuth API.

Terraform

There is an open source terraform provider which allows you to manage FusionAuth using Terraform, an open source infrastructure tool.

Here is the FusionAuth Terraform provider documentation.

There is a FusionAuth and Terraform guide which goes into more details about how use these technologies together.

Pulumi

There is a community supported, open source terraform provider which allows you to manage FusionAuth using Pulumi, an open source infrastructure tool.

Here is the FusionAuth Pulumi package documentation.

Since it is a community project, it is not as complete as the client libraries. If you find yourself needing to manage something not currently supported, you can contribute to the project using GitHub.

CLI

You can use the FusionAuth CLI to manage complex configuration such as themes.

Manual Configuration

You can manually configure FusionAuth via the administrative user interface. Changes made in this manner are recorded in the Audit Log, which you may view by navigating the System -> Audit Log.

However, while this is a good option for testing out new functionality, it is not recommended for production environments, since it depends on humans replicating configuration.

Options To Avoid

There are some options that you may think will work, but should be avoided.

Exporting and Importing the FusionAuth Database

If you are self hosting FusionAuth, you could conceivably export the database containing the FusionAuth information and import it into a new environment. You could also directly manipulate settings via SQL statements.

This is unsupported and not advised. The database structure of FusionAuth is not exposed for a reason and may change at any time. It also contains sensitive information such as passwords and user personal information that shouldn’t be shared between environments.

Kickstart

Kickstart is perfect for continuous integration (CI) as it provides full access to the FusionAuth API to configure a test instance however you want.

However, Kickstart works only on fresh installs; it doesn’t execute if the instance has previously been configured. This means it doesn’t work for managing configuration changes over time.

There is an open issue regarding Kickstart migrations, feel free to upvote it.

Learn more about Kickstart.

Other Considerations

Theme Assets

When moving themes from one environment to another, the theme logic and look and feel may be the same, but the assets may be different. FusionAuth templates only have access to the documented variables. FusionAuth does not resolve environment variables in the themes templates.

You have a few options to handle the difference in assets between theme environments.

You can set variables at theme build time in the Helpers template using the assign directive. These variables can then be used in other templates. You can use a templating language like jinja to build the Helpers template at build time.

Another option is to use custom fields in the tenant.data field. The tenant object is available to every template. Then you can reference these variables for different hostnames.

For example, if your development assets are at dev.example.com/assets and your production assets are at prod.example.com/assets, set a variable such as asset_base_url in the tenant.data field.

Here’s an excerpt of what the development tenant data object might look like:

{
  "tenant" : {
    "data" : {
      "themes": {
         "asset_base_url" : "dev.example.com/assets",
         "css_base_url" : "cdn-dev.example.com"
      }
    }
  }
}

Production, in contrast, will use different hostnames.

{
  "tenant" : {
    "data" : {
      "themes": {
         "asset_base_url" : "prod.example.com/assets",
         "css_base_url" : "cdn-prod.example.com"
      }
    }
  }
}

Then, in your template, reference images using ${tenant.data.themes.asset_base_url} and CSS files using ${tenant.data.themes.css_base_url}. For example, a simplified theme page might look like this:

<html>
  <head>
    <link rel="stylesheet" href="${tenant.data.themes.css_base_url}/css/font-awesome.min.css"/>
    <link rel="stylesheet" href="${tenant.data.themes.css_base_url}/css/app.css"/>
  </head>
  <body>
    <img src="${tenant.data.themes.asset_base_url}/logo.png" />
    ...
    <img src="${tenant.data.themes.asset_base_url}/other_image.png" />
  </body>
</html>