Skip to main content

Configuring Mango Properties

The mango.properties configuration file is one of three ways to configure Mango. You can also set environment variables or Java system properties. This flexibility is especially useful for running Mango inside containerized environments (Docker, Kubernetes) where configuration is typically injected through the environment rather than through files.

Configuration Methods​

1. Configuration File (mango.properties)​

The primary configuration file is mango.properties, located in the Mango data directory (typically /opt/mango-data/mango.properties). This file was formerly named env.properties in older versions of Mango.

Edit the file directly with a text editor:

web.port=8080
web.host=0.0.0.0
ssl.on=true
ssl.port=8443

By default, Mango monitors this file for changes and reloads settings automatically when the file is modified:

properties.reloading=true

Note that not all settings can be reloaded at runtime. Settings related to the web server, database connections, and other infrastructure typically require a restart to take effect.

2. Environment Variables​

Environment variable names are constructed from the property name by:

  1. Prefixing with mango_
  2. Replacing all periods (.) with underscores (_)

For example, paths.data becomes mango_paths_data.

Set environment variables in your shell or in your container orchestration configuration:

# Set data path via environment variable
mango_paths_data=/opt/mango-data ./bin/start-mango.sh

For Docker:

docker run -e mango_paths_data=/opt/mango-data -e mango_web_port=8080 mango-image

For Docker Compose:

services:
  mango:
    image: mango-image
    environment:
      mango_paths_data: /opt/mango-data
      mango_web_port: "8080"
      mango_ssl_on: "true"
      mango_db_type: mysql
      mango_db_url: jdbc:mysql://db-host/mango
      mango_db_username: mango
      mango_db_password: secret

3. Java System Properties​

Java system property names are constructed from the property name by prefixing with mango..

For example, paths.data becomes mango.paths.data.

Set Java system properties using the -D flag when launching Java:

java -Dmango.paths.data=/opt/mango-data -Dmango.web.port=8080 -jar bin/ma-bootstrap.jar

You can also add system properties to the start-options.sh script so they are included every time Mango starts.

Order of Precedence​

When the same property is configured through multiple methods, the following order of precedence applies (highest to lowest):

PrioritySourceExample
1 (highest)Java system property-Dmango.web.port=8080
2Environment variablemango_web_port=8080
3 (lowest)Configuration fileweb.port=8080 in mango.properties

This means a Java system property always overrides an environment variable, which always overrides a value in the configuration file. This precedence is useful for:

  • Overriding defaults for testing: Set a system property to temporarily change a setting without modifying the file.
  • Container deployments: Use environment variables to inject secrets (database passwords, SMTP credentials) without baking them into the configuration file.
  • Development vs. production: Maintain a base mango.properties file and override specific settings per environment using environment variables.

Property Variable Substitution​

Properties can reference other properties using the ${property.name} syntax:

# The SSL keystore location references the PKI keystore path
ssl.keystore.location=${pki.keyStore}

# The SSL keystore password references the PKI password
ssl.keystore.password=${pki.keyStorePassword}

This enables you to define a value once and reference it in multiple places, reducing duplication and the risk of inconsistency.

Common Configuration Scenarios​

Initial Admin User (First Start Only)​

On the first start, Mango can create an admin user automatically:

initialize.admin.create=true
initialize.admin.username=admin
initialize.admin.password=admin
initialize.admin.email=admin@localhost

Important: Do NOT set these properties in mango.properties for production. Instead, use environment variables or Java system properties during initial provisioning, and change the admin password immediately after first login.

Database Configuration​

# H2 embedded database (default)
db.type=h2
db.url=jdbc:h2:databases/mah2

# MySQL external database
db.type=mysql
db.url=jdbc:mysql://localhost/mango
db.username=mango_user
db.password=secure_password

Path Configuration​

# Mango data directory
paths.data=/opt/mango-data

# Log file directory (relative to paths.data)
paths.logs=logs

# Backup directory (relative to paths.data)
paths.backup=backup

Web Server Configuration​

web.port=8080
web.host=0.0.0.0
ssl.on=true
ssl.port=8443

File Location​

The mango.properties file is located in the Mango data directory. The data directory path can be set using:

  • The paths.data property
  • The mango_paths_data environment variable
  • The MA_HOME environment variable (legacy)

If none of these are set, the data directory defaults to the Mango installation directory.

Best Practices​

  • Use environment variables for secrets: Never store database passwords, SMTP credentials, or API keys directly in mango.properties in production. Use environment variables instead.
  • Version control your base configuration: Keep a base mango.properties in version control with non-sensitive defaults, and inject environment-specific values through environment variables.
  • Enable properties reloading for development: Set properties.reloading=true during development to avoid restarts when changing configuration.
  • Document custom properties: Add comments to mango.properties explaining why specific values were chosen for your deployment.
  • Back up the configuration file: Include mango.properties in your backup strategy along with the database and filestore.

For a complete reference of all available properties, see Mango Properties Reference.