@bostonuniversity/buwp-local 0.4.0 → 0.4.1

package/.buwp-local.json

@@ -0,0 +1,22 @@
+{
+  "projectName": "buwp-local",
+  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest",
+  "hostname": "jaydub.local",
+  "multisite": true,
+  "services": {
+    "redis": true,
+    "s3proxy": true,
+    "shibboleth": true
+  },
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306,
+    "redis": 6379
+  },
+  "mappings": [],
+  "env": {
+    "WP_DEBUG": true,
+    "XDEBUG": false
+  }
+}

package/.env.local.example

@@ -0,0 +1,26 @@
+# BU WordPress Local Development Environment Variables
+# Copy this file to .env.local and fill in your actual credentials
+# NEVER commit .env.local to version control!
+
+# Database Credentials
+WORDPRESS_DB_PASSWORD=password
+DB_ROOT_PASSWORD=rootpassword
+
+# Shibboleth Configuration (if enabled)
+SP_ENTITY_ID=https://your-sp-entity-id
+IDP_ENTITY_ID=https://shib-test.bu.edu/idp/shibboleth
+SHIB_IDP_LOGOUT=https://shib-test.bu.edu/idp/logout.jsp
+SHIB_SP_KEY=your-private-key-here
+SHIB_SP_CERT=your-certificate-here
+
+# AWS S3 Configuration (if enabled)
+S3_UPLOADS_BUCKET=your-bucket-name
+S3_UPLOADS_REGION=us-east-1
+S3_UPLOADS_ACCESS_KEY_ID=AKIA...
+S3_UPLOADS_SECRET_ACCESS_KEY=your-secret-key
+S3_ACCESS_RULES_TABLE=your-access-rules-table
+
+# OLAP Configuration (if using S3 Object Lambda)
+OLAP=your-olap-name
+OLAP_ACCT_NBR=123456789
+OLAP_REGION=us-east-1

package/USAGE.md

@@ -51,7 +51,13 @@ Edit `.buwp-local.json` to map your local repository into the container:
 
 ### 4. Create `.env.local` for secrets
 
-Create `.env.local` (never commit this file!):
+Create `.env.local` (never commit this file!) or copy from the example:
+
+```bash
+cp .env.local.example .env.local
+```
+
+Then edit `.env.local` with your actual credentials:
 
 ```bash
 # Database
@@ -70,6 +76,7 @@ S3_UPLOADS_BUCKET=your-bucket
 S3_UPLOADS_REGION=us-east-1
 S3_UPLOADS_ACCESS_KEY_ID=your-access-key
 S3_UPLOADS_SECRET_ACCESS_KEY=your-secret-key
+S3_ACCESS_RULES_TABLE=your-access-rules-table
 
 # OLAP
 OLAP=your-olap-name
@@ -77,6 +84,8 @@ OLAP_ACCT_NBR=your-account-number
 OLAP_REGION=us-east-1
 ```
 
+**Important:** Credentials are read directly from `.env.local` by Docker Compose. They are never written to the generated `docker-compose.yml` file, making it safe to review or share the generated compose file without exposing secrets.
+
 ### 5. Add hostname to /etc/hosts
 
 ```bash
@@ -226,10 +235,27 @@ Map your local code into the container:
 ## Security Best Practices
 
 1. **Never commit `.env.local`** - This file contains secrets
-2. **Never commit `.buwp-local/`** - This contains generated files
-3. **Do commit `.buwp-local.json`** - This is your configuration template
-4. **Use environment variables for all secrets**
-5. **Consider using macOS Keychain** for even better security (see docs)
+2. **Never commit `.buwp-local/`** - This directory contains generated files
+3. **Do commit `.buwp-local.json`** - This is your configuration template (no secrets)
+4. **Use environment variables for all secrets** - Credentials stay in `.env.local` and are never written to generated files
+5. **Review generated compose files** - The generated `docker-compose.yml` only contains variable references like `${WORDPRESS_DB_PASSWORD}`, not actual credentials
+6. **Copy `.env.local.example`** - Use the provided template to create your `.env.local` file
+7. **Consider using macOS Keychain** for even better security (future feature)
+
+### How Credentials Work
+
+buwp-local uses Docker Compose's native environment variable interpolation:
+
+1. **You provide** credentials in `.env.local`
+2. **buwp-local generates** `docker-compose.yml` with variable references like `${VAR_NAME}`
+3. **Docker Compose reads** `.env.local` at runtime and substitutes the values
+4. **Your secrets never** get written to any generated files
+
+This means:
+- ✅ Generated compose files are safe to review or share
+- ✅ No credentials in version control (even accidentally)
+- ✅ Industry-standard Docker Compose pattern
+- ✅ Simple and secure
 
 ## File Structure
 

package/lib/commands/init.js

@@ -133,6 +133,10 @@ async function initCommand(options) {
       name: 'hostname',
       message: 'Hostname',
       initial: (prev, values) => {
+        // For sandbox, use just username.local; for other types include project name
+        if (values.projectType === 'sandbox') {
+          return `${userName}.local`;
+        }
         return `${userName}-${values.projectName}.local`;
       },
       validate: value => {

package/lib/commands/start.js

@@ -5,7 +5,8 @@
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import path from 'path';
-import { loadConfig, validateConfig } from '../config.js';
+import fs from 'fs';
+import { loadConfig, validateConfig, ENV_FILE_NAME } from '../config.js';
 import { generateComposeFile } from '../compose-generator.js';
 
 async function startCommand(options) {
@@ -60,9 +61,13 @@ async function startCommand(options) {
     const composeDir = path.dirname(composePath);
     const projectName = config.projectName || 'buwp-local';
     
+    // Check if .env.local exists and build env-file flag
+    const envFilePath = path.join(projectPath, ENV_FILE_NAME);
+    const envFileFlag = fs.existsSync(envFilePath) ? `--env-file ${envFilePath}` : '';
+    
     try {
       execSync(
-        `docker compose -p ${projectName} -f ${composePath} up -d`,
+        `docker compose -p ${projectName} ${envFileFlag} -f ${composePath} up -d`,
         { 
           cwd: composeDir,
           stdio: 'inherit'

package/lib/compose-generator.js

@@ -57,9 +57,6 @@ function generateComposeConfig(config) {
  * @returns {object} Database service config
  */
 function generateDbService(config, dbVolumeName) {
-  const dbPassword = config.db?.password || 'password';
-  const rootPassword = config.db?.rootPassword || 'rootpassword';
-
   return {
     image: 'mariadb:latest',
     restart: 'always',
@@ -67,8 +64,8 @@ function generateDbService(config, dbVolumeName) {
     environment: {
       MYSQL_DATABASE: 'wordpress',
       MYSQL_USER: 'wordpress',
-      MYSQL_PASSWORD: dbPassword,
-      MYSQL_ROOT_PASSWORD: rootPassword
+      MYSQL_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}',
+      MYSQL_ROOT_PASSWORD: '${DB_ROOT_PASSWORD:-rootpassword}'
     },
     ports: [`${config.ports.db}:3306`],
     networks: ['wp-network']
@@ -91,7 +88,7 @@ function generateWordPressService(config, wpVolumeName) {
   const environment = {
     WORDPRESS_DB_HOST: 'db:3306',
     WORDPRESS_DB_USER: 'wordpress',
-    WORDPRESS_DB_PASSWORD: config.db?.password || 'password',
+    WORDPRESS_DB_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}',
     WORDPRESS_DB_NAME: 'wordpress',
     WORDPRESS_DEBUG: config.env?.WP_DEBUG || '0',
     SERVER_NAME: config.hostname,
@@ -104,11 +101,11 @@ function generateWordPressService(config, wpVolumeName) {
 
   // Add Shibboleth config if enabled
   if (config.services.shibboleth) {
-    environment.SP_ENTITY_ID = config.shibboleth?.entityId || '';
-    environment.IDP_ENTITY_ID = config.shibboleth?.idpEntityId || '';
-    environment.SHIB_IDP_LOGOUT = config.shibboleth?.idpLogout || '';
-    environment.SHIB_SP_KEY = config.shibboleth?.spKey || '';
-    environment.SHIB_SP_CERT = config.shibboleth?.spCert || '';
+    environment.SP_ENTITY_ID = '${SP_ENTITY_ID:-}';
+    environment.IDP_ENTITY_ID = '${IDP_ENTITY_ID:-}';
+    environment.SHIB_IDP_LOGOUT = '${SHIB_IDP_LOGOUT:-}';
+    environment.SHIB_SP_KEY = '${SHIB_SP_KEY:-}';
+    environment.SHIB_SP_CERT = '${SHIB_SP_CERT:-}';
   }
 
   // Add S3 config if enabled
@@ -130,12 +127,12 @@ function generateWordPressService(config, wpVolumeName) {
     wpConfigExtra += "define('SUBDOMAIN_INSTALL', false);\n";
   }
 
-  if (config.services.s3proxy && config.s3) {
-    wpConfigExtra += `define('S3_UPLOADS_BUCKET', '${config.s3.bucket || ''}');\n`;
-    wpConfigExtra += `define('S3_UPLOADS_REGION', '${config.s3.region || 'us-east-1'}');\n`;
-    wpConfigExtra += `define('S3_UPLOADS_KEY', '${config.s3.accessKeyId || ''}');\n`;
-    wpConfigExtra += `define('S3_UPLOADS_SECRET', '${config.s3.secretAccessKey || ''}');\n`;
-    wpConfigExtra += `define('ACCESS_RULES_TABLE', '${config.s3.accessRulesTable || ''}');\n`;
+  if (config.services.s3proxy) {
+    wpConfigExtra += "define('S3_UPLOADS_BUCKET', '${S3_UPLOADS_BUCKET}');\n";
+    wpConfigExtra += "define('S3_UPLOADS_REGION', '${S3_UPLOADS_REGION:-us-east-1}');\n";
+    wpConfigExtra += "define('S3_UPLOADS_KEY', '${S3_UPLOADS_ACCESS_KEY_ID}');\n";
+    wpConfigExtra += "define('S3_UPLOADS_SECRET', '${S3_UPLOADS_SECRET_ACCESS_KEY}');\n";
+    wpConfigExtra += "define('ACCESS_RULES_TABLE', '${S3_ACCESS_RULES_TABLE}');\n";
     wpConfigExtra += "define('S3_UPLOADS_OBJECT_ACL', null);\n";
     wpConfigExtra += "define('S3_UPLOADS_AUTOENABLE', true);\n";
     wpConfigExtra += "define('S3_UPLOADS_DISABLE_REPLACE_UPLOAD_URL', true);\n";
@@ -183,14 +180,10 @@ function generateWordPressService(config, wpVolumeName) {
 
 /**
  * Generate S3 proxy service configuration
- * @param {object} config - buwp-local configuration
+ * @param {object} _config - buwp-local configuration (unused - env vars used instead)
  * @returns {object} S3 proxy service config
  */
-function generateS3ProxyService(config) {
-  const region = config.olap?.region || config.s3?.region || 'us-east-1';
-  const olapName = config.olap?.name || '';
-  const olapAcctNbr = config.olap?.accountNumber || '';
-
+function generateS3ProxyService(_config) {
   return {
     image: 'public.ecr.aws/bostonuniversity-nonprod/aws-sigv4-proxy',
     restart: 'always',
@@ -199,16 +192,16 @@ function generateS3ProxyService(config) {
       '--name',
       's3-object-lambda',
       '--region',
-      region,
+      '${OLAP_REGION:-us-east-1}',
       '--no-verify-ssl',
       '--host',
-      `${olapName}-${olapAcctNbr}.s3-object-lambda.${region}.amazonaws.com`
+      '${OLAP}-${OLAP_ACCT_NBR}.s3-object-lambda.${OLAP_REGION:-us-east-1}.amazonaws.com'
     ],
     environment: {
       healthcheck_path: '/s3proxy-healthcheck',
-      AWS_ACCESS_KEY_ID: config.s3?.accessKeyId || '',
-      AWS_SECRET_ACCESS_KEY: config.s3?.secretAccessKey || '',
-      REGION: region
+      AWS_ACCESS_KEY_ID: '${S3_UPLOADS_ACCESS_KEY_ID}',
+      AWS_SECRET_ACCESS_KEY: '${S3_UPLOADS_SECRET_ACCESS_KEY}',
+      REGION: '${S3_UPLOADS_REGION:-us-east-1}'
     },
     networks: ['wp-network']
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bostonuniversity/buwp-local",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local WordPress development environment for Boston University projects",
   "type": "module",
   "main": "lib/index.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "buwp-local": "node bin/buwp-local.js",
+    "buwp-local": "node bin/buwp-local.js start",
     "lint": "eslint ."
   },
   "keywords": [

package/plan-environmentBasedCredentials.prompt.md

@@ -0,0 +1,57 @@
+## Plan: Environment-Based Credentials Migration (v0.4.1)
+
+We've successfully shipped v0.4.0 with interactive init, sandbox support, configurable Docker images, and smart hostname defaults. The codebase is in excellent shape with real-world testing validated in both plugin and sandbox scenarios.
+
+**Current Problem:** Credentials (database passwords, AWS keys, Shibboleth certs) are currently being read from the config/environment and then **written directly into the generated `docker-compose.yml`**. This means sensitive data sits in a generated file, which isn't ideal for security.
+
+**Better Approach:** Use Docker Compose's native environment variable interpolation (`${VAR_NAME}`) so credentials stay in `.env.local` and never get written to the compose file.
+
+### Steps
+
+1. **Update `compose-generator.js` to use environment variable references**
+   - Database service: Change from `MYSQL_PASSWORD: dbPassword` to `MYSQL_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}'`
+   - WordPress service: Change from `WORDPRESS_DB_PASSWORD: config.db?.password` to `WORDPRESS_DB_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}'`
+   - S3 proxy service: Change from `AWS_ACCESS_KEY_ID: config.s3?.accessKeyId` to `AWS_ACCESS_KEY_ID: '${S3_UPLOADS_ACCESS_KEY_ID}'`
+   - WordPress `WORDPRESS_CONFIG_EXTRA`: Change from injecting actual S3 keys to using `${S3_UPLOADS_ACCESS_KEY_ID}` references
+
+2. **Update `start.js` to pass `.env.local` to docker compose**
+   - Add `--env-file` flag to `docker compose up` command
+   - Ensure `.env.local` path is correctly resolved relative to project
+
+3. **Update config loading to remove credential reading**
+   - Keep `extractEnvVars()` for backward compatibility but mark as deprecated
+   - Config validation no longer needs to check for credential presence in config object
+   - Document that credentials should only live in `.env.local`
+
+4. **Update documentation**
+   - `USAGE.md` - Clarify that `.env.local` is the source of truth for credentials
+   - Add example showing compose file will have `${VAR}` references
+   - Security best practices section emphasizes this approach
+
+5. **Test migration path**
+   - Verify existing projects with credentials in config still work (backward compat)
+   - Test new projects using only `.env.local`
+   - Verify generated compose file contains variable references, not actual values
+   - Ensure `docker compose` properly reads `.env.local`
+
+### Further Considerations
+
+1. **Backward compatibility**: Should we warn users if credentials exist in config? Or silently prefer `.env.local`?
+2. **`.env.local` template**: Should we create `.env.local.example` during `init` command?
+3. **Validation**: Should `config --validate` check that `.env.local` exists and has required variables?
+
+---
+
+**Why This Matters:**
+- **Security**: Credentials never written to files, only referenced
+- **Git safety**: Generated compose files are safe to accidentally commit (no secrets)
+- **Best practices**: Aligns with Docker Compose's standard env var pattern
+- **Simplicity**: Reduces complexity in config merging logic
+
+**Effort Estimate:** Low-Medium (4-6 hours)
+- Compose generation changes: ~2 hours
+- Start command changes: ~1 hour  
+- Documentation: ~1 hour
+- Testing: ~1-2 hours
+
+**Ready to proceed?** This sets up a cleaner foundation before tackling Phase 2 features like keychain integration.