@bostonuniversity/buwp-local 0.1.0

package/USAGE.md

@@ -0,0 +1,258 @@
+# buwp-local Development Guide
+
+## Quick Start
+
+### 1. Install in your project
+
+```bash
+npm install --save-dev buwp-local
+```
+
+### 2. Initialize configuration
+
+```bash
+npx buwp-local config --init
+```
+
+This creates `.buwp-local.json` in your project directory.
+
+### 3. Edit configuration
+
+Edit `.buwp-local.json` to map your local repository into the container:
+
+```json
+{
+  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest",
+  "hostname": "myproject.local",
+  "multisite": true,
+  "mappings": [
+    {
+      "local": "./",
+      "container": "/var/www/html/wp-content/plugins/my-plugin"
+    }
+  ]
+}
+```
+
+### 4. Create `.env.local` for secrets
+
+Create `.env.local` (never commit this file!):
+
+```bash
+# Database
+WORDPRESS_DB_PASSWORD=password
+DB_ROOT_PASSWORD=rootpassword
+
+# Shibboleth (if needed)
+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-key-here
+SHIB_SP_CERT=your-cert-here
+
+# AWS S3 (if needed)
+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
+
+# OLAP
+OLAP=your-olap-name
+OLAP_ACCT_NBR=your-account-number
+OLAP_REGION=us-east-1
+```
+
+### 5. Add hostname to /etc/hosts
+
+```bash
+sudo bash -c 'echo "127.0.0.1 username.local" >> /etc/hosts'
+```
+
+### 6. Start the environment
+
+```bash
+npx buwp-local start
+```
+
+### 7. Access your site
+
+Open http://username.local or https://username.local in your browser.
+
+## Commands
+
+### Start environment
+```bash
+npx buwp-local start [options]
+
+Options:
+  --xdebug       Enable Xdebug
+  --no-s3        Disable S3 proxy service
+  --no-redis     Disable Redis service
+```
+
+### Stop environment
+```bash
+npx buwp-local stop
+```
+
+### View logs
+```bash
+npx buwp-local logs [options]
+
+Options:
+  -f, --follow              Follow log output
+  -s, --service <service>   Show logs for specific service
+                            (wordpress, db, s3proxy, redis)
+```
+
+### Destroy environment
+```bash
+npx buwp-local destroy [options]
+
+Options:
+  -f, --force    Skip confirmation prompt
+```
+
+### Configuration management
+```bash
+npx buwp-local config [options]
+
+Options:
+  --init        Initialize configuration file
+  --validate    Validate configuration file
+  --show        Show resolved configuration (with masked secrets)
+```
+
+## Configuration File
+
+### Basic Structure
+
+```json
+{
+  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest",
+  "hostname": "wordpress.local",
+  "multisite": true,
+  "services": {
+    "redis": true,
+    "s3proxy": true,
+    "shibboleth": true
+  },
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306,
+    "redis": 6379
+  },
+  "mappings": [],
+  "env": {}
+}
+```
+
+### Volume Mappings
+
+Map your local code into the container:
+
+```json
+{
+  "mappings": [
+    {
+      "local": "./",
+      "container": "/var/www/html/wp-content/plugins/my-plugin"
+    },
+    {
+      "local": "../my-theme",
+      "container": "/var/www/html/wp-content/themes/my-theme"
+    }
+  ]
+}
+```
+
+### Custom Environment Variables
+
+```json
+{
+  "env": {
+    "WP_DEBUG": true,
+    "WP_DEBUG_LOG": true,
+    "XDEBUG": false
+  }
+}
+```
+
+### Disabling Services
+
+```json
+{
+  "services": {
+    "redis": false,
+    "s3proxy": false,
+    "shibboleth": false
+  }
+}
+```
+
+## 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)
+
+## File Structure
+
+When you use `buwp-local`, these files are created:
+
+```
+your-project/
+├── .buwp-local.json        # Configuration (commit this)
+├── .env.local              # Secrets (NEVER commit)
+├── .buwp-local/            # Generated files (don't commit)
+│   └── docker-compose.yml  # Generated compose file
+└── package.json            # Your project
+```
+
+## Troubleshooting
+
+### Port conflicts
+
+If you get port conflicts, you can change ports in `.buwp-local.json`:
+
+```json
+{
+  "ports": {
+    "http": 8080,
+    "https": 8443,
+    "db": 3307,
+    "redis": 6380
+  }
+}
+```
+
+### Docker not running
+
+Make sure Docker Desktop is running:
+```bash
+docker info
+```
+
+### Configuration errors
+
+Validate your configuration:
+```bash
+npx buwp-local config --validate
+```
+
+### View current configuration
+
+See the resolved configuration (with masked secrets):
+```bash
+npx buwp-local config --show
+```
+
+## Next Steps
+
+- [ ] Phase 2: WP-CLI proxy command
+- [ ] Phase 2: macOS Keychain integration
+- [ ] Phase 3: Automatic /etc/hosts management
+- [ ] Phase 3: SSL certificate generation

package/bin/buwp-local.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+/**
+ * buwp-local CLI
+ * Main entry point for the BU WordPress Local development environment tool
+ */
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const packageJson = require('../package.json');
+
+// Import commands
+const startCommand = require('../lib/commands/start');
+const stopCommand = require('../lib/commands/stop');
+const destroyCommand = require('../lib/commands/destroy');
+const logsCommand = require('../lib/commands/logs');
+const configCommand = require('../lib/commands/config');
+
+const program = new Command();
+
+program
+  .name('buwp-local')
+  .description('Local WordPress development environment for Boston University projects')
+  .version(packageJson.version);
+
+// Start command
+program
+  .command('start')
+  .description('Start the local WordPress environment')
+  .option('--xdebug', 'Enable Xdebug')
+  .option('--no-s3', 'Disable S3 proxy service')
+  .option('--no-redis', 'Disable Redis service')
+  .action(startCommand);
+
+// Stop command
+program
+  .command('stop')
+  .description('Stop the local WordPress environment')
+  .action(stopCommand);
+
+// Destroy command
+program
+  .command('destroy')
+  .description('Destroy the local WordPress environment (removes volumes)')
+  .option('-f, --force', 'Skip confirmation prompt')
+  .action(destroyCommand);
+
+// Logs command
+program
+  .command('logs')
+  .description('View logs from the WordPress environment')
+  .option('-f, --follow', 'Follow log output')
+  .option('-s, --service <service>', 'Show logs for specific service (wordpress, db, s3proxy, redis)')
+  .action(logsCommand);
+
+// Config command
+program
+  .command('config')
+  .description('Configuration management')
+  .option('--init', 'Initialize configuration file')
+  .option('--plugin', 'Initialize with plugin mapping (use with --init)')
+  .option('--mu-plugin', 'Initialize with mu-plugin mapping (use with --init)')
+  .option('--theme', 'Initialize with theme mapping (use with --init)')
+  .option('--validate', 'Validate configuration file')
+  .option('--show', 'Show resolved configuration')
+  .action(configCommand);
+
+// WP-CLI proxy command
+program
+  .command('wp <args...>')
+  .description('Run WP-CLI commands in the WordPress container')
+  .allowUnknownOption()
+  .action((args) => {
+    console.log(chalk.yellow('WP-CLI proxy not yet implemented'));
+    console.log('Would run:', args.join(' '));
+  });
+
+// Error handling
+program.exitOverride();
+
+try {
+  program.parse(process.argv);
+} catch (err) {
+  if (err.code === 'commander.help' || err.code === 'commander.version') {
+    // Normal exit for help/version
+    process.exit(0);
+  }
+  console.error(chalk.red('Error:'), err.message);
+  process.exit(1);
+}
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/docker-compose.yml

@@ -0,0 +1,106 @@
+# Complete local development environment for BU WordPress
+# Includes database, WordPress, S3 proxy, and Redis services
+
+services:
+  db:
+    image: mariadb:latest
+    restart: always
+    volumes:
+      - db_data:/var/lib/mysql
+    environment:
+      MYSQL_DATABASE: wordpress
+      MYSQL_USER: wordpress
+      MYSQL_PASSWORD: ${WORDPRESS_DB_PASSWORD:-password}
+      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-rootpassword}
+    ports:
+      - "3306:3306"
+    networks:
+      - wp-network
+
+  wordpress:
+    # If DOCKER_REGISTRY is set, pull the image from there; otherwise, use the locally built image
+    image: ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest
+    depends_on:
+      - db
+      - s3proxy
+      - redis
+    restart: always
+    ports:
+      - "80:80"
+      - "443:443"
+    hostname: ${WP_HOSTNAME:-wordpress.local}
+    environment:
+      WORDPRESS_DB_HOST: db:3306
+      WORDPRESS_DB_USER: wordpress
+      WORDPRESS_DB_PASSWORD: ${WORDPRESS_DB_PASSWORD:-password}
+      WORDPRESS_DB_NAME: wordpress
+      WORDPRESS_DEBUG: ${WORDPRESS_DEBUG:-0}
+      SERVER_NAME: ${WP_HOSTNAME:-wordpress.local}
+      HTTP_HOST: ${WP_HOSTNAME:-wordpress.local}
+      SP_ENTITY_ID: ${SP_ENTITY_ID:-https://*.kualitest.research.bu.edu/shibboleth}
+      IDP_ENTITY_ID: ${IDP_ENTITY_ID:-https://shib-test.bu.edu/idp/shibboleth}
+      SHIB_IDP_LOGOUT: ${SHIB_IDP_LOGOUT:-https://shib-test.bu.edu/idp/logout.jsp}
+      SHIB_SP_KEY: ${SHIB_SP_KEY}
+      SHIB_SP_CERT: ${SHIB_SP_CERT}
+      S3PROXY_HOST: http://s3proxy:8080
+      FORWARDED_FOR_HOST: ${FORWARDED_FOR_HOST:-localhost}
+      REDIS_HOST: redis
+      REDIS_PORT: 6379
+      TZ: America/New_York
+      MULTISITE: true
+      XDEBUG: ${XDEBUG:-false}
+      WP_CLI_ALLOW_ROOT: true
+      # S3 WordPress config
+      WORDPRESS_CONFIG_EXTRA: |
+        define('MULTISITE', true);
+        define('SUBDOMAIN_INSTALL', false);
+        define( 'S3_UPLOADS_BUCKET', '${S3_UPLOADS_BUCKET}');
+        define( 'S3_UPLOADS_REGION', '${S3_UPLOADS_REGION}');
+        define( 'S3_UPLOADS_SECRET', '${S3_UPLOADS_SECRET_ACCESS_KEY}');
+        define( 'S3_UPLOADS_KEY', '${S3_UPLOADS_ACCESS_KEY_ID}');
+        define( 'ACCESS_RULES_TABLE', '${ACCESS_RULES_TABLE}');
+        define( 'S3_UPLOADS_OBJECT_ACL', null);
+        define( 'S3_UPLOADS_AUTOENABLE', true );
+        define( 'S3_UPLOADS_DISABLE_REPLACE_UPLOAD_URL', true);
+        define( 'BU_INCLUDES_PATH', '/var/www/html/bu-includes' );
+    volumes:
+      - wp_build:/var/www/html
+      - /Users/jaydub/CodeProjects/github/bu-media-s3:/var/www/html/wp-content/mu-plugins/bu-media-s3
+    networks:
+      - wp-network
+
+  s3proxy:
+    image: public.ecr.aws/bostonuniversity-nonprod/aws-sigv4-proxy
+    restart: always
+    command: 
+      - "-v"
+      - "--name"
+      - "s3-object-lambda"
+      - "--region"
+      - "${OLAP_REGION:-us-east-1}"
+      - "--no-verify-ssl"
+      - "--host"
+      - "${OLAP}-${OLAP_ACCT_NBR}.s3-object-lambda.${OLAP_REGION:-us-east-1}.amazonaws.com"
+    environment:
+      healthcheck_path: '/s3proxy-healthcheck'
+      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
+
+  redis:
+    image: redis:alpine
+    restart: always
+    ports:
+      - "6379:6379"
+    networks:
+      - wp-network
+
+networks:
+  wp-network:
+    driver: bridge
+
+volumes:
+  db_data:
+  wp_build:

package/lib/commands/config.js

@@ -0,0 +1,131 @@
+/**
+ * Config command - Configuration management
+ */
+
+const chalk = require('chalk');
+const { loadConfig, validateConfig, initConfig, CONFIG_FILE_NAME } = require('../config');
+
+async function configCommand(options) {
+  try {
+    const projectPath = process.cwd();
+
+    // Initialize configuration
+    if (options.init) {
+      console.log(chalk.blue('📝 Initializing configuration...\n'));
+      
+      // Determine initialization type
+      const initOptions = {};
+      if (options.plugin) {
+        initOptions.plugin = true;
+        console.log(chalk.gray('Creating plugin configuration...'));
+      } else if (options.muPlugin) {
+        initOptions.muPlugin = true;
+        console.log(chalk.gray('Creating mu-plugin configuration...'));
+      } else if (options.theme) {
+        initOptions.theme = true;
+        console.log(chalk.gray('Creating theme configuration...'));
+      }
+      
+      try {
+        const configPath = initConfig(projectPath, initOptions);
+        console.log(chalk.green(`✅ Created configuration file: ${configPath}\n`));
+        
+        if (initOptions.plugin || initOptions.muPlugin || initOptions.theme) {
+          const path = require('path');
+          const projectName = path.basename(projectPath);
+          const type = initOptions.plugin ? 'plugin' : initOptions.muPlugin ? 'mu-plugin' : 'theme';
+          console.log(chalk.cyan(`Auto-configured mapping for ${type}: ${projectName}`));
+        }
+        
+        console.log(chalk.gray('Edit this file to customize your environment.'));
+        console.log(chalk.gray('Then run "buwp-local start" to launch your environment.\n'));
+      } catch (err) {
+        if (err.message.includes('already exists')) {
+          console.log(chalk.yellow(`⚠️  ${CONFIG_FILE_NAME} already exists.\n`));
+        } else {
+          throw err;
+        }
+      }
+      return;
+    }
+
+    // Validate configuration
+    if (options.validate) {
+      console.log(chalk.blue('🔍 Validating configuration...\n'));
+      
+      const config = loadConfig(projectPath);
+      const validation = validateConfig(config);
+
+      if (validation.valid) {
+        console.log(chalk.green('✅ Configuration is valid!\n'));
+      } else {
+        console.log(chalk.red('❌ Configuration has errors:\n'));
+        validation.errors.forEach(error => {
+          console.log(chalk.red(`  - ${error}`));
+        });
+        console.log('');
+        process.exit(1);
+      }
+      return;
+    }
+
+    // Show resolved configuration
+    if (options.show) {
+      console.log(chalk.blue('📄 Resolved configuration:\n'));
+      
+      const config = loadConfig(projectPath);
+      
+      // Mask sensitive values
+      const maskedConfig = maskSensitiveData(config);
+      
+      console.log(JSON.stringify(maskedConfig, null, 2));
+      console.log('');
+      return;
+    }
+
+    // No options provided, show help
+    console.log(chalk.yellow('Usage: buwp-local config [options]\n'));
+    console.log('Options:');
+    console.log('  --init               Initialize configuration file');
+    console.log('  --init --plugin      Initialize with plugin mapping');
+    console.log('  --init --mu-plugin   Initialize with mu-plugin mapping');
+    console.log('  --init --theme       Initialize with theme mapping');
+    console.log('  --validate           Validate configuration file');
+    console.log('  --show               Show resolved configuration\n');
+
+  } catch (err) {
+    console.error(chalk.red('\n❌ Error:'), err.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Mask sensitive data in configuration
+ * @param {object} config - Configuration object
+ * @returns {object} Configuration with masked sensitive data
+ */
+function maskSensitiveData(config) {
+  const masked = JSON.parse(JSON.stringify(config));
+
+  // Mask database passwords
+  if (masked.db) {
+    if (masked.db.password) masked.db.password = '***MASKED***';
+    if (masked.db.rootPassword) masked.db.rootPassword = '***MASKED***';
+  }
+
+  // Mask Shibboleth credentials
+  if (masked.shibboleth) {
+    if (masked.shibboleth.spKey) masked.shibboleth.spKey = '***MASKED***';
+    if (masked.shibboleth.spCert) masked.shibboleth.spCert = '***MASKED***';
+  }
+
+  // Mask S3 credentials
+  if (masked.s3) {
+    if (masked.s3.accessKeyId) masked.s3.accessKeyId = '***MASKED***';
+    if (masked.s3.secretAccessKey) masked.s3.secretAccessKey = '***MASKED***';
+  }
+
+  return masked;
+}
+
+module.exports = configCommand;

package/lib/commands/destroy.js

@@ -0,0 +1,96 @@
+/**
+ * Destroy command - Destroys the local WordPress environment (including volumes)
+ */
+
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const readline = require('readline');
+const { loadConfig } = require('../config');
+
+async function destroyCommand(options) {
+  console.log(chalk.red('⚠️  DESTROY BU WordPress local environment\n'));
+
+  try {
+    const projectPath = process.cwd();
+    const composePath = path.join(projectPath, '.buwp-local', 'docker-compose.yml');
+
+    // Check if docker-compose.yml exists
+    if (!fs.existsSync(composePath)) {
+      console.log(chalk.yellow('⚠️  No environment found to destroy.\n'));
+      return;
+    }
+
+    // Load config to get project name
+    const config = loadConfig(projectPath);
+    const projectName = config.projectName || 'buwp-local';
+
+    // Confirm destruction unless --force flag is used
+    if (!options.force) {
+      const confirmed = await confirmDestroy(projectName);
+      if (!confirmed) {
+        console.log(chalk.gray('Destroy cancelled.\n'));
+        return;
+      }
+    }
+
+    // Check if Docker is running
+    try {
+      execSync('docker info', { stdio: 'ignore' });
+    } catch (err) {
+      console.error(chalk.red('❌ Docker is not running.'));
+      process.exit(1);
+    }
+
+    // Destroy Docker Compose (down with volumes)
+    console.log(chalk.gray('\nRemoving containers and volumes...\n'));
+    const composeDir = path.dirname(composePath);
+    
+    try {
+      execSync(
+        `docker compose -p ${projectName} -f ${composePath} down -v`,
+        { 
+          cwd: composeDir,
+          stdio: 'inherit'
+        }
+      );
+    } catch (err) {
+      console.error(chalk.red('\n❌ Failed to destroy Docker environment'));
+      process.exit(1);
+    }
+
+    console.log(chalk.green('\n✅ Environment destroyed successfully!\n'));
+    console.log(chalk.gray('Use "buwp-local start" to create a fresh environment.\n'));
+
+  } catch (err) {
+    console.error(chalk.red('\n❌ Error:'), err.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Prompt user for confirmation
+ * @param {string} projectName - Name of the project being destroyed
+ * @returns {Promise<boolean>}
+ */
+function confirmDestroy(projectName) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    console.log(chalk.yellow(`This will destroy project: ${chalk.bold(projectName)}`));
+    console.log(chalk.yellow('  - Stop all containers'));
+    console.log(chalk.yellow('  - Remove all containers'));
+    console.log(chalk.yellow('  - Delete all volumes (including database data)\n'));
+
+    rl.question(chalk.red('Are you sure you want to continue? (yes/no): '), (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'yes' || answer.toLowerCase() === 'y');
+    });
+  });
+}
+
+module.exports = destroyCommand;