Advanced configuration
Introduction
Mingle configuration options are managed in a configuration directory outside of the installation folder. Having the ability to manage these outside the installation folder means that upgrading your Mingle instance and keeping your existing configuration is now much easier.
Do not alter your Mingle configuration unless you completely understand the impact of the change. We recommend discussing any configuration changes you are unsure of with the Mingle support team before they are made.
Specifying a configuration directory
The config directory (configDir) is where Mingle will store project configuration files such as database.yml. If unspecified, this defaults to ${mingle.dataDir}/config
To avoid problems with future upgrades, this directory should not reside within the Mingle installation folder.
Note that if you are pointing an existing Mingle installation to a new configDir location, remember to move the contents of the configDir and review the settings for correctness.
Unix platforms:
Add the following command-line option:
--mingle.configDir=/path/to/your/configDir
Windows:
On Windows, you can set the config directory during installation.
If configuring this directory without using the installer, add the following line to the Mingle.vmoptions within your Mingle installation folder:
-Dmingle.configDir=Drive:\path\to\your\configDir
mingle.properties configuration options
Please refer to the mingle.properties.example file in your Mingle installation folder as an example of the latest mingle.properties format.
Configuring site URLs
These properties are typically specified by the Mingle administrator during the browser-based install or upgrade sequence. However, if the administrator wishes to change these values or set -Dmingle.secureSiteURL at a later date it is necessary to directly edit the mingle.properties file.
In general, Mingle generates URLs that are relative to the base URL of the request. However, there are scenarios, such as sending emails and URLs in the event API, where Mingle cannot rely upon publishing URLs relative to a request. For this reason, it is necessary to specify the -Dmingle.siteURL property. The value of this property should be the base URL by which your users access Mingle. If you have fronted Mingle with a reverse proxy, this value should be the base URL for the proxy and not the internal Mingle address. This URL should contain the port if your base URL contains is a non-standard port.
Here is an example for a typical usage without a reverse proxy and without SSL
-Dmingle.siteURL=http://mingle.example.com:8080
Here is what a reverse proxy listening on default HTTP port of 80 configuration might look like
-Dmingle.siteURL=http://mingle.example.com
-Dmingle.port=8080
Certain features in Mingle, such as Go integration, require an HTTPS(SSL) endpoint. If you have configured the value of -Dmingle.siteURL to an HTTPS base URL, Mingle will use that value when it must display a secure URL. However, if you wish that your primary site URL be HTTP, but still want to have HTTPS endpoints for the features that require SSL, you can specify an optional -Dmingle.secureSiteURL property with a value of the base HTTPS URL.
-Dmingle.siteURL=http://mingle.example.com
-Dmingle.secureSiteURL=https://mingle.example.com
Configuring a swap directory
The swap directory (swapDir) will act as a tmp space in which to store intermediate data such as project exports (.mingle files) while they are being created, project import files that are being imported, excel import content that is being processed for preview and excel import content that is being processed for import.
This directory should not be within the Mingle installation folder. To avoid problems with future upgrades, please keep this directory separate from the Mingle installation.
On Windows, you can set the swap directory during installation. Additionally, on every platform you can specify a property in mingle.properties to set the swap directory as follows:
-Dmingle.swapDir=/path/to/your/data/tmp
If unspecified, a default context path of /dataDir/tmp will be used.
Configuring a port
On Windows, you can set the network port during installation. Additionally, on every platform you can specify a property in mingle.properties to set the network port from which to run Mingle as follows:
-Dmingle.port=1234
If unspecified, a default of '8080' will be used.
This property is only used to configure the port to which Mingle binds on its host machine. Be sure to also configure -Dmingle.siteURL (discussed above) to the value of the base URL through which users will access Mingle.
Configuring an alternate app context
You can specify a property in mingle.properties to set an alternate app context as follows:
-Dmingle.appContext=/mingle
If specified, this will configure an app context of /mingle respectively. If unspecified, a default context path of / will be used.
Configuring the log directory
You can specify a property which is the directory you would like to have your logs written to, such as /var/log, as follows:
-Dmingle.logDir=/path/to/log/dir
If unspecified, a default value of "log", under the installation folder, is used.
Configuring the memcached host and port
You can specify two properties in mingle.properties to set a memcache host and port as follows:
-Dmingle.memcachedHost=mingle.mingle.com -Dmingle.memcachedPort=11311
This will connect to a memcached server at mingle.mingle.com:11311. If not specified, the default values are localhost & 11211 respectively.
Configuring SSL Access
You can turn on Jetty's SSL listener for HTTPS access by configuring a few properties in mingle.properties as follows:
-Dmingle.ssl.port=8443 -Dmingle.ssl.keystore=/PATH/TO/KEYSTORE -Dmingle.ssl.keystorePassword=PASSWORD_TO_ACCESS_KEYSTORE -Dmingle.ssl.keyPassword=KEY_PASSPHRASE
You can have both HTTP and HTTPS enabled for Mingle by setting proper values for both the -Dmingle.port property and the entire -Dmingle.ssl.* section.
You can disable HTTP or HTTPS by not setting either of -Dmingle.port or -Dmingle.ssl.port.
If neither -Dmingle.port nor -Dmingle.ssl.port is given, a default of "8080" for -Dmingle.port will be used.
Your keystore (mingle.ssl.keystore) is a file in which keys and certificates are stored. Mingle requires access to it to provide secure HTTPS connections. Your certificate will need to be imported into this keystore. You can find more information on creating and managing a keystore here.
We recommend storing your keystore in a directory outside of Mingle's install folder so that the keystore does not need to be moved during subsequent Mingle upgrades.
Your keystore file is password protected, so you need to provide your keystore password as mingle.ssl.keystorePassword.
The mingle.ssl.keyPassword entry should contain your key's password.
These properties are only used to configure the SSL port to which Mingle binds on its host machine. Be sure to also configure -Dmingle.siteURL (see advanced configuration) to match the new HTTPS URL.
Configuring search engine listener port
If needed, you can change the two ports Mingle uses for its search engine by editing the [mingle_install_dir]/config/elasticsearch.yml file.
transport.tcp.port: 9300
http.port: 9200
Local help
Mingle help is located on the ThoughtWorks Studios website. The Mingle help files are also packaged with your local Mingle instance. In cases where network access is limited, you may want Mingle to link to your local help rather than the online help.
Online help has several advantages to local help. Consider the following before you switch to local help:
- Online help has a search feature (added in Mingle 3.2); local help cannot be searched.
- Online help may be more up to date than local help. As we make updates to help, we are able to post the latest help online.
Linking to local Mingle help
-
Open [mingle_root]/config/initializers/document.rb
-
Change HELP_DOC_DOMAIN from
HELP_DOC_DOMAIN = ONLINE_HELP_DOC_DOMAIN
to
HELP_DOC_DOMAIN = ""