Skip to content

environment-variables.md

Latest commit

 

History

History
235 lines (164 loc) · 23.5 KB

environment-variables.md

File metadata and controls

235 lines (164 loc) · 23.5 KB
order 5

Environment Variables

[!INFO] The MicroPowerManager follows The Twelve-Factor App principle. MicroPowerManager's configuration is separated from the code base and can be done via environment variables.

In this document we describe the most relevant environment variables and highlight the ones which are required to be populated for MicroPowerManager to function properly.

Frontend

Backend connection

Environment Variable Default Description
MPM_ENV Required Environment identifier for the MicroPowerManager frontend. Can be development, demo or production. Recommended to set to production in production environments. Note: This is different from the builtin NODE_ENV environment variable.
MPM_BACKEND_URL Required The URL of the MicroPowerManager backend. For example http://localhost:8000 (for non-local) or https://demo-backend.micropowermanager.io (for production).
VUE_APP_CUSTOM_HEADERS none (Development only) Provide any optional, custom headers that should be present on all requests to the MicroPowerManager backend. Can be used for example to surpress Ngrok warning pages with {"ngrok-skip-browser-warning": true}
VUE_APP_MPM_BACKEND_URL_EXTERNAL ${MPM_BACKEND_URL} (Development only) Useful when the MicroPowerManager URL for external services is different from localhost. Can be used when developing third party plugins that expose a local machine via reverse tunnels. For example VUE_APP_MPM_BACKEND_URL_EXTERNAL=https://randomly-generated-url.ngrok-free.dev

Backend

Because MicroPowerManager is based on Laravel and Laravel Plugins a lot of behaviour can be configured using environment variables.

For more details see the corresponding plugin's documentation.

Laravel

Environment Variable Default Description
APP_NAME MicroPowerManager Display Name of the Application
APP_ENV development Environment identifier for the MicroPowerManager backend. Can be development, demo or production. Recommended to set to production in production environments.
APP_DEBUG True Whether or not to run MicroPowerManager in debug mode. Recommended to set to false in production environments.
APP_KEY Required Used by the Illuminate encrypter service to encrypt database entries. In production environments make sure this is a random, 32 character string, otherwise these encrypted strings will not be safe
APP_URL http://localhost:8000 Set this to root of MicroPowerManager in deployed environments (production or demo).

MicroPowerManager

These environment variables control how the MicroPowerManager behaves as an application.

Environment Variable Default Description
MPM_FRONTEND_URL Required The URL where MicroPowerManager frontend is located, this is required for email password reset and other related functionality that requires Knowledge of the frontend.
MPM_LOAD_DEMO_DATA false Whether or not the demo data should be loaded when the MicroPowerManager starts for the first time. Recommended for local development and demo environments. Optional for production environments.
MPM_FORCE_OPTIMIZE false Force Laravel optimization (php artisan optimize) on container startup even when not in production mode. Set to true to enable. Optimization runs automatically when APP_ENV=production.

JSON Web Token Authentication (jwt-auth)

For more details see jwt-auth documentation.

Environment Variable Default Description
JWT_SECRET Required jwt-auht secret, ideally created with php artisan jwt:secret.

Database connection

Environment Variable Default Description
DB_CONNECTION micro_power_manager Name of the laravel default connection. Should almost never be changed.
DB_HOST Required Network host name the database is accessible from. For example db (for local) or long-url.my-cloud-provider.com/region/db (for dedicated databases).
DB_PORT 3306 Database port.
DB_DATABASE micro_power_manager Database name.
DB_USERNAME Required Database username. For example root.
DB_PASSWORD Required Database password. For example password123!

Redis connection

We recommend running MicroPowerManager with Redis.

Environment Variable Default Description
REDIS_HOST Required (If Redis is used) Network host name the Redis cluster is accessible from. For example redis (for local) or long-url.my-cloud-provider.com/region/db (for dedicated Redis cluster).
REDIS_PASSWORD Required (If Redis is used) Password for Redis.
REDIS_PORT 6379

Caching

We recommend running MicroPowerManager with Redis for caching.

Environment Variable Default Description
CACHE_DRIVER file Recommended to set to redis.

Session management

Environment Variable Default Description
SESSION_DRIVER file
SESSION_LIFETIME 120

Broadcasting

We recommend running MicroPowerManager with Pusher Channels for broadcasting.

Environment Variable Default Description
BROADCAST_DRIVER null Recommended to set to pusher.
PUSHER_APP_ID Required (If Pusher is used) Pusher App id.
PUSHER_APP_KEY Required (If Pusher is used) Pusher App key.
PUSHER_APP_SECRET Required (If Pusher is used) Pusher App secret.
PUSHER_APP_CLUSTER Required (If Pusher is used) Pusher App cluster. For example eu.

File Storage

MicroPowerManager supports multiple storage backends for file storage. Configure the following environment variables based on your chosen storage provider.

Storage Configuration

Environment Variable Default Description
FILESYSTEM_DISK local The default storage disk to use (local, s3, or gcs).

Amazon S3 Storage

Environment Variable Default Description
AWS_ACCESS_KEY_ID null Your AWS access key ID.
AWS_SECRET_ACCESS_KEY null Your AWS secret access key.
AWS_DEFAULT_REGION null The AWS region where your S3 bucket is located.
AWS_BUCKET null The name of your S3 bucket.
AWS_USE_PATH_STYLE_ENDPOINT false Set to true if using S3-compatible services that require path-style URLs.

Google Cloud Storage

Environment Variable Default Description
GOOGLE_CLOUD_PROJECT_ID null Your Google Cloud project ID.
GOOGLE_CLOUD_STORAGE_BUCKET null The name of your GCS bucket.
GOOGLE_CLOUD_KEY_FILE null Path to a service account JSON key file.
GOOGLE_CLOUD_KEY_JSON null Your service account JSON key file content (as a JSON string). Will be used only if GOOGLE_CLOUD_KEY_FILE is not provided.

To learn more about working with GCS in Laravel, the official library will be a vaulable guide.

Basic setup

Logging

Set of environment variables that can be used to configure logging and logging providers in MicroPowerManager.

Environment Variable Default Description
LOG_CHANNEL mpm_stack The default value mpm_stack configures a split logging where error logs go to STDERR and application info and debug logs to STDOUT. Additional log channels to external logging solutions are automatically enabled, if corresponding environment variables are configured, see below. For more information about available log channels, see logging.php.
LOG_LEVEL debug General log level of the application. Note, that external logging systems may define their log level seperately. For example, it might be desired to only send critical errors to Slack, even if MicroPowerManager runs with an elevanted log level of info. Recommended to set this at least info or hire in normal operations of a production environment.

Slack

Environment Variable Default Description
LOG_SLACK_LEVEL critical The log level sent to Slack. URL
LOG_SLACK_WEBHOOK_URL Required (When using Slack Logging) Slack Webhook URL for logging. This requires a Slack incoming webhook. If LOG_SLACK_WEBHOOK_URL is provided Slack logging will be enabled.
LOG_SLACK_USERNAME Laravel Log Slack Webhook Username
LOG_SLACK_EMOJI :boom: Slack Webhook Emoji

Email

Configure the following environment variable to enable MicroPowerManager to send email via SMTP. These configure instance level email sent to tenants, for example signup confirmation, password reset, etc...

Environment Variable Default Description
MAIL_FROM_ADDRESS hello@example.com Global "from" address for all emails sent by the application.
MAIL_FROM_NAME Example Global "from" name for all emails sent by the application.

Using SMTP Email Service

To Configure email with SMTP follow the official guidge.

Laravel Horizon and Horizon Dashboard

MicroPowerManager internally uses Laravel Horizon to manage it's queue workers.

By default Horizon Dashboard will not be accessible in non-development environments. Configure the below environment variables to enable HTTP Basic Auth. Only if both HORIZON_BASIC_AUTH_USERNAME and HORIZON_BASIC_AUTH_PASSWORD are set, HTTP Basic Auth is enabled.

Environment Variable Default Description
HORIZON_BASIC_AUTH_USERNAME null HTTP Basic Auth Username for Horizon Dashboard.
HORIZON_BASIC_AUTH_PASSWORD null HTTP Basic Auth Username for Horizon Dashboard..

Configure Horizon notifications

Environment Variable Default Description
HORIZON_SLACK_WEBHOOK_URL null Slack Webhook URL for Horizon notifications. This requires a Slack incoming webhook. If HORIZON_SLACK_WEBHOOK_URL is provided Horizon Slack notifications will be enabled. Note: Can be the same webhook as LOG_SLACK_WEBHOOK_URL.

Laravel Telescope and Telescope Dashboard

MicroPowerManager internally uses Laravel Telescope for peformance monitoring and debugging.

By default Telescope will be disabled. Configure the below environment variables to enable Telescope and secure the dashboard with HTTP Basic Auth.

Environment Variable Default Description
TELESCOPE_ENABLED false Enable or disable Telescope data collection and dashboard.
TELESCOPE_BASIC_AUTH_USERNAME null HTTP Basic Auth Username for Telescope Dashboard.
TELESCOPE_BASIC_AUTH_PASSWORD null HTTP Basic Auth Password for Telescope Dashboard.
TELESCOPE_PRUNE_HOURS 48 Number of hours to retain Telescope data before pruning. Increase for extended debugging periods (e.g., 168 for 7 days, 336 for 14 days).

MPM Plugins

Certain MicroPowerManager plugins require configuration before they can be used. Find below a reference of configurations which are required if the corresponding plugin is used.

SunKing

For detailed information see SunKing Developer Documentation

Environment Variable Default Description
SUNKING_AUTH_DEFAULT_URL https://auth.central.glpapps.com/auth/realms/glp-dev/protocol/openid-connect/token Default authorisation URL used when tenants activate the SunKing plugin on the instance of MicroPowerManager.
SUNKING_API_DEFAULT_URL https://dev.assetcontrol.central.glpapps.com/v2 Default API URL used when tenants activate the SunKing plugin on the instance of MicroPowerManager.

WaveMoney

For detailed information see WaveMoney Developer Documentation

Environment Variable Default Description
WAVEMONEY_API_URL Required (when plugin is used) WaveMoney API URL. For example https://preprodpayments.wavemoney.io:8107.

Paystack

For detailed information see Paystack Developer Documentation

Environment Variable Default Description
PAYSTACK_COMPANY_HASH_SALT APP_KEY Salt used for generating company-specific payment URLs. Defaults to the application key.
PAYSTACK_API_TIMEOUT 30 API request timeout in seconds.
PAYSTACK_VERIFY_WEBHOOK_SIGNATURE true Whether to verify Paystack webhook signatures for security.
PAYSTACK_DEFAULT_CURRENCY NGN Default currency for Paystack transactions.
PAYSTACK_SUPPORTED_CURRENCIES NGN,GHS,KES,ZAR Comma-separated list of supported currencies for Paystack transactions.