Environment Variables
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the use of environment variables for configuring the zalopay application. The system relies on environment variables to manage settings for different deployment environments (development, testing, production), separating sensitive data and environment-specific parameters from the source code. This approach is facilitated by the dotenv package, which loads variables from a .env file into the application's process environment.
The core of the configuration logic resides in config/config.js, which reads the process environment and exports a structured configuration object. This object provides a centralized and consistent way for different parts of the application, such as database connections and ZaloPay API integrations, to access necessary settings.
Sources: config/config.js, index.js:3, .env.example
Configuration Loading Mechanism
The application initializes its configuration at startup. The main entry point, index.js, is responsible for loading the environment variables from a .env file before any other application logic is executed.
This is achieved by calling require('dotenv').config() at the top of the index.js file. The dotenv library, listed as a dependency in package.json, reads the key-value pairs from the .env file in the project's root directory and adds them to the process.env object in the Node.js runtime. Subsequently, the config/config.js module accesses process.env to build and export the final configuration object used throughout the application.
Sources: index.js:3, package.json:18
The following diagram illustrates the loading flow of environment variables.
This diagram shows the sequence from application startup to the point where configuration is available to all modules.
Sources: index.js:3, config/config.js:3-10
Configuration Structure
The primary configuration file, config/config.js, defines the structure of the application's configuration. It reads environment variables and organizes them into a nested object, with top-level keys for different environments like development, test, and production. The NODE_ENV environment variable determines which of these configurations is exported for use by the application.
The main properties within each environment's configuration are:
- app: General application settings like the port.
- db: Database connection details.
- zalo: ZaloPay-specific credentials and settings.
Sources: config/config.js
Environment-Specific Configuration
The config.js file exports a configuration object corresponding to the value of process.env.NODE_ENV. If NODE_ENV is not set, it defaults to development.
// config/config.js:3-10
const env = process.env.NODE_ENV || 'development';
const config = {
development: {
// ... development config
},
test: {
// ... test config
},
// ... other environments
};
module.exports = config[env];
This structure allows the application to switch between different settings, such as using a local database for development and a production database in the production environment, simply by changing the NODE_ENV variable.
Sources: config/config.js:3-10
Core Environment Variables
The .env.example file serves as a template, listing all the required environment variables for the application to function correctly. A .env file, which is not committed to version control, should be created based on this template with the actual values for the specific environment.
The following table details the environment variables defined in .env.example.
| Variable | Description | Example Value |
|---|---|---|
NODE_ENV | The application environment. Determines which configuration block from config.js is used. | development |
PORT | The port on which the web server will listen. | 3000 |
DB_CONNECTION | The database driver. | mysql |
DB_HOST | The hostname of the database server. | 127.0.0.1 |
DB_PORT | The port of the database server. | 3306 |
DB_DATABASE | The name of the database to use. | zalopay |
DB_USERNAME | The username for the database connection. | root |
DB_PASSWORD | The password for the database connection. | |
APP_ID | The Application ID provided by ZaloPay. | 2553 |
KEY1 | The first key (Key1) provided by ZaloPay for request signing. | PcY4iZIKFCIdgZvA6ueMcMHHUbRLYjPL |
KEY2 | The second key (Key2) provided by ZaloPay for callback verification. | kLtgPl8HHhgwUPBGwsdYyYsKFcuYIaPm |
CALLBACK_URL | The URL that ZaloPay will send callback requests to after a transaction. | https://sondk.dev/ |
Sources: .env.example:1-12
Usage in Application
Once loaded, the configuration object is imported by various modules that require access to environment-specific settings. A primary consumer of this configuration is the common/zalo.js module, which handles interactions with the ZaloPay API.
This module imports the configuration and uses values like app_id, key1, key2, and callback_url to construct API requests and verify callbacks.
// common/zalo.js:1-2
const config = require('../config/config').zalo;
const CryptoJS = require('crypto-js');
// ...
// common/zalo.js:10
const embed_data = {
redirecturl: config.callback_url
};
// ...
// common/zalo.js:20
const hmac = CryptoJS.HmacSHA256(data, config.key1);
The routes/index.js file also uses the configuration to pass the app_id to the views, which might be used on the client-side.
Sources: common/zalo.js:1,10,20, routes/index.js:8
ZaloPay Payment Flow
The following sequence diagram shows how the configuration is used when a user initiates a payment request.
This diagram illustrates how the ZaloModule retrieves credentials from the configuration object to create a signed payment request.
Sources: routes/index.js:20-29, common/zalo.js:5-30
Summary
The zalopay application's configuration is managed through environment variables, adhering to Twelve-Factor App principles. The dotenv package loads variables from a .env file, and config/config.js structures them for different environments (development, production, etc.). This setup provides a secure and flexible way to manage application settings, from server ports and database credentials to third-party API keys for ZaloPay, without hardcoding them into the source code.
Sources: index.js, config/config.js, .env.example