# Update Environment Variables Script This script is part of the **BWS-Secure** project, located under the `/update-environments/` directory. It facilitates the management and synchronization of environment variables across **Netlify** and **Vercel** platforms, ensuring consistency and security. ## Table of Contents 1. Overview 2. Environment Management - Environment Mapping - Platform Support - File Structure 3. Configuration - Prerequisites - Project Configuration - Required Variables 4. Usage - Basic Usage - Platform-Specific Usage 5. Debugging - Debug Variables - Debugging File Mappings - Troubleshooting 6. Platform Details - Netlify - Vercel - Local Development 7. Advanced Topics - Token Handling - Error Handling - API Rate Limits --- ## Overview The `updateEnvVars.js` script: - Processes all projects configured for the detected platform - Updates each project's variables only once (prevented by BWS_ENV_UPDATED flag) - Supports multiple projects per platform in bwsconfig.json - Can handle both Netlify and Vercel projects simultaneously - Maintains separate environments (prod/dev) per project If you are using the **BWS-Secure run wrapper**, for testing or general use, run the script using the following command: ```bash pnpm secure-run node /update-environments/updateEnvVars.js ``` --- ## Environment Management ### Environment Mapping The system maps Netlify deployment contexts to Bitwarden Secrets Manager (BWS) project environments: - **Production**: Uses the BWS project ID specified in `bwsProjectIds.prod` - **Deploy Preview**: Uses the BWS project ID from `bwsProjectIds.dev` by default - **Branch Deploy**: Uses the BWS project ID from `bwsProjectIds.dev` by default #### Optional Environment Customization For more granular control, you can specify separate BWS project IDs for different Netlify contexts: ```json { "platform": "netlify", "projectName": "your-site-name", "bwsProjectIds": { "prod": "production-bws-project-id", // BWS Project ID for production "dev": "development-bws-project-id", // BWS Project ID for development "local": "local-development-bws-id", // BWS Project ID for local dev "deploy_preview": "preview-bws-id", // Optional: specific BWS Project ID for deploy previews "branch_deploy": "branch-bws-id" // Optional: specific BWS Project ID for branch deploys } } ``` - If `deploy_preview` BWS project ID is specified, it will be used for deploy previews instead of `dev` - If `branch_deploy` BWS project ID is specified, it will be used for branch deploys instead of `dev` - If neither is specified, the `dev` BWS project ID is used as a fallback for all non-production contexts This allows you to: - Use the same variables for all non-production builds (default behavior using `dev`) - Set up separate variables for deploy previews - Configure branch-specific variables - Mix and match as needed ### Platform Support The script supports both Netlify and Vercel platforms. ### File Structure The script uses a structured approach to manage environment variables: - **bwsconfig.json**: Defines projects and configurations. - **requiredVars.env**: Lists mandatory variables. - **.env**: Contains platform-specific tokens and variables. --- ## Configuration ### Prerequisites 1. **Node.js**: Ensure you have Node.js installed. 2. **Environment Variables**: Add the required tokens to your `.env` file for local testing or development: ```env NETLIFY_AUTH_TOKEN=your_netlify_token BWS_ACCESS_TOKEN=your_access_token ``` **Note**: `BWS_ACCESS_TOKEN` is primarily for local testing. During builds, tokens are securely retrieved from Bitwarden or specific platform configurations. ### Project Configuration Define your projects and configurations in a `bwsconfig.json` file: ```json { "projects": [ { "platform": "vercel", "projectName": "your-vercel-project-name", "bwsProjectIds": { "prod": "00000000-0000-0000-0000-000000000001", // Bitwarden Secrets Manager Project ID for production "dev": "00000000-0000-0000-0000-000000000002", // BWS Project ID for development "local": "00000000-0000-0000-0000-000000000003" // BWS Project ID for local development }, "preserveVars": ["BWS_ACCESS_TOKEN"] }, { "platform": "netlify", "projectName": "your-netlify-site-name", "bwsProjectIds": { "prod": "00000000-0000-0000-0000-000000000004", "dev": "00000000-0000-0000-0000-000000000005", "local": "00000000-0000-0000-0000-000000000006" }, "preserveVars": ["BWS_ACCESS_TOKEN"] } ] } ``` - **platform**: Specify either `netlify` or `vercel`. - **projectName**: The project name in Netlify/Vercel. - **bwsProjectIds**: Map of Bitwarden Secrets Manager Project IDs for different environments. - These IDs are found in your Bitwarden Secrets Manager interface. - Each ID corresponds to a separate BWS project containing environment variables for that context. - Not to be confused with Netlify/Vercel project IDs. - **preserveVars**: List of variables to retain unchanged. - **exclusions**: List of variables to ignore during synchronization. ### Required Variables Define mandatory variables in the `requiredVars.env` file: ```env API_KEY=your_api_key DATABASE_URL=your_database_url SECRET_KEY=example_secret_key ANOTHER_VAR=another_value ``` --- ## Usage ### Basic Usage The script is typically run through the secure-run wrapper during platform builds: ```bash # For Netlify: NETLIFY=true pnpm secure-run your-command # For Vercel: VERCEL=1 pnpm secure-run your-command ``` When run this way: 1. Platform is detected automatically 2. All matching projects are processed 3. Each project is updated only once 4. Variables are synchronized with the platform ### Platform-Specific Usage - **Netlify**: - Retrieves existing environment variables for a site. - Updates variables with new values. - Excludes or preserves variables as specified in `bwsconfig.json`. - **Vercel**: - Uses `vercel env ls --json` to list variables. - Updates variables with `vercel env add`. ### Options - `--platform, -p`: Specify the deployment platform (Netlify or Vercel). - `--help, -h`: Show help information. - `--validateRequiredVars`: Validate the `requiredVars.env` file. --- ## Debugging ### Debug Variables The environment mapping system supports several debug flags: ```bash # Environment Variables DEBUG=true # Enable debug logging SHOW_DECRYPTED=true # Show decrypted environment contents BWS_ENV=local|dev|prod # Specify environment BWS_PROJECT=name # Specify project name VERBOSE=true # Enable verbose logging ``` ### Debugging File Mappings The system creates symlinks from project ID based files to named environment files: ``` .env.secure. -> .env.secure.. ``` To debug these mappings: ```bash # Show all mappings DEBUG=true pnpm secure-run # Show mappings and decrypted contents DEBUG=true SHOW_DECRYPTED=true pnpm secure-run # Debug specific environment mapping DEBUG=true SHOW_DECRYPTED=true BWS_ENV=dev pnpm secure-run ``` ### Debugging File Contents When using `DEBUG=true SHOW_DECRYPTED=true`, the system will: - Only decrypt and display the current environment's file - Show contents in a formatted blue box - Maintain all necessary symlinks for platform deployments - Keep sensitive data secure in other environments ### Troubleshooting 1. Check file existence and mappings: ```bash DEBUG=true pnpm secure-run ``` 2. Verify file contents: ```bash DEBUG=true SHOW_DECRYPTED=true pnpm secure-run ``` 3. Debug specific project/environment: ```bash DEBUG=true SHOW_DECRYPTED=true BWS_PROJECT=my-project BWS_ENV=dev pnpm secure-run ``` 4. Full debug output: ```bash DEBUG=true VERBOSE=true SHOW_DECRYPTED=true pnpm secure-run ``` The system will show: - Which files are being created - Symlink mappings - Decrypted contents (if SHOW_DECRYPTED=true) - Any errors or warnings during the process --- ## Platform Details ### Netlify #### Environment Variables Management - Retrieves existing environment variables for a site. - Updates variables with new values. - Excludes or preserves variables as specified in `bwsconfig.json`. #### Testing To test locally: ```bash node updateEnvVars.js --netlifyTest --netlifySiteId your-site-id --netlifyToken your-netlify-token --netlifyKey TEST_VAR ``` ### Vercel #### Environment Variables Management - Uses `vercel env ls --json` to list variables. - Updates variables with `vercel env add`. #### Status Work in progress. Similar to Netlify, but with minor differences in API handling. ### Local Development Local development defaults to: - Uses `local` BWS project ID - Can be overridden with `BWS_ENV` environment variable --- ## Advanced Topics ### Token Handling Tokens such as `NETLIFY_AUTH_TOKEN` are required for API operations. The `getBuildOrAuthToken` function prioritizes tokens from environment variables and ensures their validity. If a token is missing, the script will terminate with an error message. During testing, you can use `.env` files for token storage. ### Error Handling Errors are logged and optionally terminate the script. Examples: - **Fatal Errors**: Halt execution with detailed stack traces (in development mode). - **Warnings**: Non-critical issues logged for user review. You can control the termination behavior of errors by passing the `fatal` parameter to the `handleError` function. ### API Rate Limits Both Netlify and Vercel impose rate limits on API requests. The script includes basic error handling to detect and log rate limit errors. For high-frequency operations, consider: - Batching updates where possible. - Avoiding excessive retries. - Implementing delays or exponential backoff for retries.