Environment
Introduction
The following environment variables configure a Metaport CE server, and are read by the application at runtime; those marked as required must be present for Metaport to start and operate correctly.
| Variable | Purpose | Type | Required |
|---|---|---|---|
SS_ENVIRONMENT_TYPE |
Set to one of dev, test, or live. Gates production hardening, such as disabling development tasks. |
String | Y |
SS_DATABASE_SERVER |
The hostname, IP, or container service name for Metaport's database server. | String | Y |
SS_DATABASE_NAME |
The name of Metaport's database as managed by the database server e.g. metaport. |
String | Y |
SS_DATABASE_USERNAME |
The username for connecting to Metaport's database. | String | Y |
SS_DATABASE_PASSWORD |
The password for connecting to Metaport's database. | String | Y |
DB_ROOT_PASSWORD |
The database superuser password. Not read by Metaport itself; it is consumed by the database server to provision the database on first run, and is unnecessary if you supply your own database. | String | Y |
SS_ALLOWED_HOSTS |
Comma-separated list of hostnames Metaport will answer to. If unset, Metaport logs a warning that it may be vulnerable to host-header injection. | String | N |
SS_DEFAULT_ADMIN_USERNAME |
The username for a default admin user. Can be an email or a simple string. If this or the corresponding password is unset, no default admin is created. | String | N |
SS_DEFAULT_ADMIN_PASSWORD |
The password for the default admin user. | String | N |
MP_PRIMARY_DOMAIN |
The domain this Metaport server runs on. Emitted in API responses for CORS compatibility. | String | Y |
MP_MASTER_LOG_PATH |
Path to Metaport's master log file. Recommended for development only. | String | Y |
MP_REDIS_HOST |
The Redis/Valkey/Dragonfly connection URL used for Metaport's cache, e.g. redis://cache:6379. |
String | Y |
MP_DOWNLOAD_DIR |
Directory for generated file downloads such as reports and exports. Defaults to the system temporary directory. | String | N |
MP_MAIL_DSN |
The SMTP connection details for a Metaport server, in the form smtp://<user>:<pass>@<host>:<port>. Use null://default to discard all mail. |
String | Y |
MP_NOTIFICATION_EMAIL_FROM |
Sets the From header for all emails sent from Metaport. Policy notifications fail if this is unset. |
String | Y |
MP_NOTIFICATION_EMAIL_REPLYTO |
Sets the Reply-To header for all emails sent from Metaport. |
String | N |
MP_MASTER_KEY_PATH |
Path to the master encryption key file. Metaport fails at start-up if the file is missing or unreadable. Recommend this for development only. Use a secrets manager in production. | String | Y |
MP_RECAPTCHA_SITEKEY |
The Google reCAPTCHA v3 site key. See the note on reCAPTCHA below. | String | Y |
MP_RECAPTCHA_SECRETKEY |
The Google reCAPTCHA v3 secret key. See the note on reCAPTCHA below. | String | Y |
MP_RECAPTCHA_SPAMLEVEL |
The reCAPTCHA score threshold as a percentage from 0 to 100, e.g. 50. See the note on reCAPTCHA below. |
Int | Y |
SS_MFA_SECRET_KEY |
The encryption secret used for generating OTP codes for use with MFA. Accounts created under a different key will not work. | String | N |
BYPASS_MFA |
Disables MFA enforcement when set. Intended for development and testing only. | Int | N |
MP_SECRETS_BACKEND |
The short-name of the pluggable secrets backend, e.g. Vault. If unset, Metaport uses the file-system master key. |
String | N |
MP_VAULT_HOST |
The full scheme and hostname where your Vault host can be found. | String | N |
MP_VAULT_TRANSIT_KEY |
The name of the stored transit key in Vault, e.g. organisation-encryption. |
String | N |
MP_VAULT_ROLE_ID |
The Vault AppRole role_id. An identifier, not itself a secret. |
String | N |
MP_VAULT_SECRET_ID |
The Vault AppRole secret_id. |
String | N |
MP_COMPONENT_MANAGER |
The short-name of the pluggable EOL backend, e.g. EndOfLifeDotDate. Component EOL lookups are disabled when unset. |
String | Y |
MP_CALENDAR_ENABLED |
1 or 0. Enables the shared maintenance calendar. Disabled when unset. |
Int | N |
MP_APP_ICON_ENABLE |
1 or 0. Enables application icon uploads. Disabled when unset. Uploaded image-paths are obfuscated, but not unguessable. |
Int | N |
REGISTRATION_ENABLED |
1 or 0. Allows users to register directly from a URL route. See the note on registration below. |
Int | N |
ENABLE_COMPONENT_MANAGEMENT |
1 or 0. Enables the component selection field in the CMS settings - admin users only. |
Int | N |
MP_ENABLE_HYDRATION |
1 or 0. Seeds demonstration data for newly registered users. |
Int | N |
MP_UTILITY_LINKS |
Optional, additional utility links to appear for non-admin users. Comma-separated entries of the form link;Label;icon-class. |
String | N |
MP_API_UA |
The User-Agent header sent to integration backends. Defaults to metaport. |
String | N |
MP_LOCATION_HEADER_NAME |
The name of an HTTP header whose value seeds a new team's location, e.g. a CDN geo-location header. | String | N |
MP_PLUGIN_UTIL_DIR |
Directory holding SBOM files used when seeding demonstration data. | String | N |
MP_PLUGIN_SKIPPED |
Comma-separated list of agent names to omit from agent selection, e.g. PHP/Composer. |
String | N |
MP_IS_CI |
1 or 0. Signals to various subsystems that an invocation is part of a CI pipeline, which marks ingested data as "Provisional". |
Int | N |
KEYCLOAK_URL |
For use with Keycloak IDP: the full scheme, host and port of the Keycloak server. | String | N |
KEYCLOAK_REALM |
For use with Keycloak IDP: the realm to use with the connected Keycloak server. | String | N |
KEYCLOAK_CLIENT_ID |
For use with Keycloak IDP: the identifier of the client configured within the connected Keycloak server. Also suppresses username and password registration. | String | N |
KEYCLOAK_CLIENT_SECRET |
For use with Keycloak IDP: the auto-generated secret of the client configured within the connected Keycloak server. | String | N |
KEYCLOAK_REDIRECT_URI |
For use with Keycloak IDP: the full scheme, domain and route where authentication requests are sent. Must match Keycloak's "Valid redirect URIs" field. | String | N |
ENTRA_CLIENT_ID |
For use with Microsoft Entra ID: the client identifier. Also suppresses username and password registration. | String | N |
ENTRA_CLIENT_SECRET |
For use with Microsoft Entra ID: the client secret. | String | N |
ENTRA_REDIRECT_URI |
For use with Microsoft Entra ID: the full scheme, domain and route where authentication requests are sent. | String | N |
GOOGLE_SSO_CLIENT_ID |
For use with Google SSO: the client identifier. | String | N |
GOOGLE_SSO_CLIENT_SECRET |
For use with Google SSO: the client secret. | String | N |
GOOGLE_SSO_REDIRECT_URI |
For use with Google SSO: the full scheme, domain and route where authentication requests are sent. | String | N |
GITHUB_SSO_CLIENT_ID |
For use with Github SSO: the client identifier. | String | N |
GITHUB_SSO_CLIENT_SECRET |
For use with Github SSO: the client secret. | String | N |
GITHUB_SSO_REDIRECT_URI |
For use with Github SSO: the full scheme, domain and route where authentication requests are sent. | String | N |
BEHAT_BASE_URL |
For Behat testing: the base URL the test suite drives. Setting this also puts Metaport into test mode, so never set it in production. | String | N |
BEHAT_REDIRECT_URI |
For Behat testing: the OAuth callback route used by the mock identity provider. | String | N |
MOCK_KEYCLOAK_ENABLED |
For Behat testing: substitutes a mock Keycloak provider for the real one. | Int | N |
Note
The three MP_RECAPTCHA_* variables must be set together. Metaport builds a reCAPTCHA field on its login, registration, lost-password and change-password forms unconditionally, and that field requires all three. If any one of them is missing, those forms cannot be built and login is unavailable.
Note
Each SSO provider is enabled only when every variable in its group is set. Setting some but not all of a provider's variables disables that provider and will not report an error.
Note
REGISTRATION_ENABLED is necessary but not sufficient. Username and password registration is additionally suppressed whenever KEYCLOAK_CLIENT_ID or ENTRA_CLIENT_ID is set, so that Keycloak or Entra remains the sole route in. Google and Github SSO do not have this effect.
Note
The MP_VAULT_* variables must all be set together once MP_SECRETS_BACKEND selects the Vault backend. See the secrets documentation for the full set-up procedure.
Tip
Variables consumed by an agent running inside one of your own monitored applications, rather than by the Metaport server, are documented separately in the agent documentation.