Configuring Morgana

The guide explains the configuration methods for Morgana and how to start and apply the preferred configuration. It includes configuration guidelines for optimizing Morgana for faster startup and low memory footprint.

Configuration Sources for Morgana

Morgana loads the configuration from four different configuration sources:

• command-line parameters

• environment variables

• user-created .conf file

• morgana.conf file located in the conf directory

Configuration sources have a descending ordinal: command-line parameters take precedence over environment variables. Environment variables take precedence over options set by using a specific configuration file. Options from a specific config file take precedence over options defined in conf/morgana.conf. When the same configuration key is found in multiple configuration sources, the applied value is taken from the configuration source with the highest ordinal.

Start Morgana

Morgana can be started in two operating modes, developement mode and production mode. Both modes offer a different set of defaults for the environment they are intended to be used.

Starting Morgana in Development Mode

The development mode is targeted at people trying out Morgana for the first time and getting it up and running quickly. It also offers convenient defaults for developers, for example, to develop a new Morgana theme.

The development mode is started by invoking the following command:

bin/kc.[sh|bat] start-dev

The development mode sets the following default configuration:

• HTTP is enabled

• Strict hostname resolution is disabled

• The Cache is set to local (No distributed cache mechanism used for high availability)

• Theme - and Template-caching is disabled

Starting Morgana in Production Mode

The production mode is targeted for developers of Morgana into production environments and follows a "secure by default" principle.

The production mode is started by invoking the following command:

bin/kc.[sh|bat] start

Without further configuration, this command will not start Morgana and show you an error instead. This is done on purpose, because Morgana follows a "secure by default" principle in this mode and expects to have a hostname setup and an HTTPS/TLS setup available when started in production mode.

The production mode sets the following defaults:

• HTTP is disabled as transport layer security (HTTPs) is essential

• Hostname configuration is expected

• HTTPS/TLS configuration is expected

By default, the example configuration options for the production mode are commented out in the default conf/morgana.conf file. These give you an idea about the main configuration to consider when running Morgana in production.

Underlying Concepts

Morgana uses the Quarkus framework and it's re-augmentation/mutable-jar approach under the covers. This process is started when a build is invoked.

The following are some optimizations performed by the build command:

• A new closed-world assumption about installed providers is created, meaning that no need exists to re-create the registry and initialize the factories at every Morgana startup

• Configuration files are pre-parsed to reduce IO when starting the server

• Database-specific resources are configured and prepared to run against a certain database vendor

• By persisting build options into the server image, the server does not perform any additional step to interpret configuration options and configure itself

You can read more at the specific Quarkus guide 🚀.