Configuration Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Configuration management in this project is handled through environment variables, providing a flexible and consistent way to configure the application across different environments such as local development, testing, and production. The system relies on .env files, which are loaded into the application's runtime environment.
A key feature of this system is the startup validation process, which ensures that all required environment variables are present and meet certain criteria before the application starts. This prevents runtime errors due to misconfiguration. The configuration approach is standardized for both local development via pnpm scripts and for Docker-based deployments.
Sources: SETUP.md, deploys/README.md, libs/shared/config/env.validation.ts
Core Concepts
Environment Variable Files
The project uses a standard .env file-based approach for managing environment-specific configurations.
- .env.example: A template file that lists all the necessary environment variables. It should be copied to create a local configuration file.
- .env: The actual configuration file used for local development and Docker deployments. This file is listed in
.gitignoreand should never be committed to the repository.
The typical workflow for a new setup is to copy the example file and populate it with the correct values for the target environment.
cp .env.example .env
nano .env
Sources: SETUP.md:14-16, deploys/README.md:145-147
Startup Validation
To ensure system stability, a validation function validateEnvironment is executed at application startup. This function checks for the presence of all critical environment variables and performs basic sanity checks.
The validation flow is as follows:
This diagram illustrates the environment validation process at application startup.
Sources: libs/shared/config/env.validation.ts:7-32
The validation function checks for the following:
- Presence of Required Variables: It iterates through a predefined list of essential variables and throws a fatal error if any are missing.
- JWT Secret Key Length: It checks if
JWT_SECRET_KEYis at least 32 characters long and logs a warning if it's not, to enforce security best practices.
Sources: libs/shared/config/env.validation.ts:16-31, libs/shared/config/env.validation.spec.ts:102-113
Configuration Variables
The following table details the environment variables used across the system for local development and Docker deployments.
| Variable | Description | Example | Source File |
|---|---|---|---|
DOCKER_USERNAME | The username for the Docker Hub registry to pull images from. | your_docker_username | deploys/README.md:195 |
VERSION | The version tag for the Docker images to be deployed. | v1.0.0 | deploys/README.md:196 |
NATS_URL | The connection URL for the NATS message broker. | nats://nats-server-ip:4222 | deploys/README.md:199 |
DATABASE_URL_USER | PostgreSQL connection string for the User service database. | postgresql://postgres:password@db-server:5432/user_db | deploys/README.md:202 |
DATABASE_URL_PRODUCT | PostgreSQL connection string for the Product service database. | postgresql://postgres:password@db-server:5432/product_db | deploys/README.md:203 |
DATABASE_URL_ORDER | PostgreSQL connection string for the Order service database. | postgresql://postgres:password@db-server:5432/order_db | deploys/README.md:204 |
DATABASE_URL_CART | PostgreSQL connection string for the Cart service database. | postgresql://postgres:password@db-server:5432/cart_db | deploys/README.md:205 |
DATABASE_URL_PAYMENT | PostgreSQL connection string for the Payment service database. | postgresql://postgres:password@db-server:5432/payment_db | deploys/README.md:206 |
DATABASE_URL_REPORT | PostgreSQL connection string for the Report service database. | postgresql://postgres:password@db-server:5432/report_db | deploys/README.md:207 |
DATABASE_URL_AR | PostgreSQL connection string for the AR service database. | postgresql://postgres:password@db-server:5432/ar_db | deploys/README.md:208 |
JWT_SECRET_KEY | A secret key for signing JWTs. Must be at least 32 characters. | your_super_secret_key_min_32_chars_here | SETUP.md:18 |
CORS_ORIGIN | A comma-separated list of allowed origins for CORS. | http://localhost:3001,http://localhost:4200 | SETUP.md:21 |
LOG_LEVEL | The logging level for the application. | debug | QUICK_START.md:52 |
NODE_ENV | The application environment. | production | QUICK_START.md:53 |
Database Configuration
Each microservice connects to its own dedicated PostgreSQL database. The connection strings are managed via a set of DATABASE_URL_* environment variables.
getDatabaseUrl Helper
A helper function, getDatabaseUrl, is provided to retrieve the correct database URL for a specific service. It dynamically constructs the environment variable key based on the service name.
// From libs/shared/config/env.validation.ts
export const getDatabaseUrl = (service: ServiceName): string => {
const key = `DATABASE_URL_${service.toUpperCase()}`;
const url = process.env[key];
if (!url) {
throw new Error(`Database URL not found for service: ${service}`);
}
return url;
};
Sources: libs/shared/config/env.validation.ts:34-42
The following diagram shows how a service retrieves its database connection string.
This sequence diagram illustrates the process of a service obtaining its database URL.
Sources: libs/shared/config/env.validation.ts:34-42
Usage in Different Environments
Local Development
For local development, developers should copy .env.example to .env in the project root. This file is then used by pnpm scripts (like pnpm dev:all) to configure all microservices running locally. The dotenv-cli package is used in testing scripts to load test-specific environment variables.
Sources: SETUP.md:14-16, package.json:30
Docker Deployment
During Docker deployment, a .env file is placed in the deploys/ directory on the host machine. The deploy.sh script reads this file and passes the variables to the docker compose command, which in turn injects them into the respective service containers.
This ensures that deployed containers are configured with production-ready values for databases, NATS, and other external services.
Sources: deploys/README.md:145-152, QUICK_START.md:31-34
CI/CD Pipeline
In the CI/CD environment (GitHub Actions), configuration is managed via GitHub Secrets. Sensitive values like DOCKER_USERNAME and DOCKER_PASSWORD are stored as encrypted secrets in the repository settings and are securely exposed to the workflow runners as environment variables.
# Example from .github/workflows/docker-push.yml
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
This approach avoids hardcoding credentials in the workflow files.
Sources: CI_CD_SETUP.md:31-37
Summary
The project's configuration management is built on the robust and widely-adopted practice of using environment variables. It is enhanced with a crucial startup validation step to catch misconfigurations early. The use of .env files provides flexibility, while the consistent approach across local, Docker, and CI/CD environments simplifies development and deployment workflows. The system is designed to be secure by separating configuration from code and using secrets management tools in automated pipelines.