| layout | title | description | navcategory |
|---|---|---|---|
doc |
Configuration Management |
Manage FusionAuth configuration changes over time. |
admin |
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?
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).
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.
There is a community supported, open source terraform provider which allows you to manage FusionAuth using Terraform, an open source infrastructure as code automation tool.
For more details, see our Terraform documentation.
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.
You can use the FusionAuth CLI to manage complex configuration such as themes.
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.
There are some options that you may think will work, but should be avoided.
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 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.
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 does not resolve any environment variables in the themes, or anything other than what is documented.
You can set your own variables in the Helpers template using assign that can be used in other templates. You could use a templating language like jinja to build the Helpers template at build time and then a script to load it during deploy.
You may also use the tenant.data field, as the tenant object will always be available for any theme. For example, if you have your development assets at dev.example.com/assets and your production assets at prod.example.com/assets you could set a variable in tenant.data: tenant.data.themes.asset_url to be either of these values, then reference ${tenant.data.themes.asset_url}/logo.png (for your logo) in your templates.