@bostonuniversity/buwp-local 0.5.2 → 0.6.0

package/docs/MULTI_PROJECT.md

@@ -0,0 +1,513 @@
+# Multi-Project Support
+
+Learn how to run multiple buwp-local projects simultaneously, either isolated or integrated.
+
+## Overview
+
+buwp-local supports two multi-project strategies:
+
+1. **Isolated Environments** - Each project runs independently with its own database and WordPress
+2. **Shared Environments** - Multiple repositories share one WordPress instance for integration testing
+
+## Isolated Environments
+
+### How It Works
+
+Each project gets a unique name (based on directory name) and isolated Docker volumes:
+
+- **Database volume:** `{projectName}_db_data`
+- **WordPress volume:** `{projectName}_wp_build`
+- **Container names:** `{projectName}-wordpress-1`, `{projectName}-db-1`, etc.
+
+This means:
+✅ Each project has its own database  
+✅ Each project has its own WordPress installation  
+✅ Projects don't interfere with each other  
+✅ You can run multiple projects simultaneously
+
+### Setting Up Multiple Projects
+
+**Step 1: Initialize each project**
+
+```bash
+# Plugin A
+cd ~/projects/bu-custom-analytics
+npx buwp-local init --plugin
+
+# Plugin B  
+cd ~/projects/bu-slideshow
+npx buwp-local init --plugin
+
+# Theme
+cd ~/projects/responsive-framework
+npx buwp-local init --theme
+```
+
+**Step 2: Configure different ports (optional)**
+
+Edit `.buwp-local.json` in each project to avoid port conflicts:
+
+```json
+// bu-custom-analytics
+{
+  "ports": {
+    "http": 8080,
+    "https": 8443
+  }
+}
+
+// bu-slideshow
+{
+  "ports": {
+    "http": 8081,
+    "https": 8444
+  }
+}
+
+// responsive-framework
+{
+  "ports": {
+    "http": 8082,
+    "https": 8445
+  }
+}
+```
+
+**Step 3: Add hostnames to /etc/hosts**
+
+```bash
+sudo bash -c 'cat >> /etc/hosts << EOF
+127.0.0.1 bu-custom-analytics.local
+127.0.0.1 bu-slideshow.local
+127.0.0.1 responsive-framework.local
+EOF'
+```
+
+**Step 4: Start all projects**
+
+```bash
+cd ~/projects/bu-custom-analytics && npx buwp-local start
+cd ~/projects/bu-slideshow && npx buwp-local start
+cd ~/projects/responsive-framework && npx buwp-local start
+```
+
+**Step 5: Access your sites**
+
+- http://bu-custom-analytics.local:8080
+- http://bu-slideshow.local:8081
+- http://responsive-framework.local:8082
+
+### Managing Multiple Projects
+
+**View running projects in Docker Desktop:**
+
+```
+Containers:
+├─ bu-custom-analytics
+│  ├─ bu-custom-analytics-wordpress-1
+│  ├─ bu-custom-analytics-db-1
+│  └─ bu-custom-analytics-redis-1
+│
+├─ bu-slideshow
+│  ├─ bu-slideshow-wordpress-1
+│  ├─ bu-slideshow-db-1
+│  └─ bu-slideshow-redis-1
+│
+└─ responsive-framework
+   ├─ responsive-framework-wordpress-1
+   ├─ responsive-framework-db-1
+   └─ responsive-framework-redis-1
+```
+
+**Stop a specific project:**
+
+```bash
+cd ~/projects/bu-custom-analytics
+npx buwp-local stop
+```
+
+**View logs for a specific project:**
+
+```bash
+cd ~/projects/bu-slideshow
+npx buwp-local logs -f
+```
+
+---
+
+## Shared Environments
+
+### When to Use Shared Environments
+
+Use a shared environment when you need to:
+- ✅ Test how multiple plugins work together
+- ✅ Develop theme + plugins simultaneously
+- ✅ Mirror production configuration locally
+- ✅ Test plugin interactions with real data
+- ✅ Collaborate on integrated features
+
+### How It Works
+
+By giving multiple repositories the **same `projectName`**, they join the same Docker Compose project and share:
+- Database (one shared MySQL instance)
+- WordPress installation (one shared wp_build volume)
+- Services (Redis, S3 proxy, etc.)
+
+### Setup: Primary + Secondary Pattern
+
+This is the recommended approach for shared environments.
+
+#### Primary Repository
+
+Create a "primary" repository that owns the base configuration:
+
+```bash
+mkdir ~/projects/bu-sandbox-primary
+cd ~/projects/bu-sandbox-primary
+npx buwp-local init
+```
+
+Edit `.buwp-local.json`:
+
+```json
+{
+  "projectName": "bu-sandbox",
+  "hostname": "bu-sandbox.local",
+  "multisite": true,
+  "services": {
+    "redis": true,
+    "s3proxy": true,
+    "shibboleth": true
+  },
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306
+  },
+  "mappings": [],
+  "env": {
+    "WP_DEBUG": true
+  }
+}
+```
+
+Create shared credentials:
+
+```bash
+# Either use Keychain (recommended)
+npx buwp-local keychain setup --file ~/Downloads/credentials.json
+
+# Or create .env.local
+cp .env.local.example .env.local
+# Edit with credentials
+```
+
+Start the base environment:
+
+```bash
+npx buwp-local start
+```
+
+#### Secondary Repositories
+
+Add your plugin/theme repositories to the shared environment:
+
+```bash
+cd ~/projects/bu-custom-analytics
+npx buwp-local init --plugin
+```
+
+Edit `.buwp-local.json` to use the **same projectName**:
+
+```json
+{
+  "projectName": "bu-sandbox",  // Same as primary!
+  "hostname": "bu-sandbox.local",
+  "multisite": true,
+  "services": {
+    "redis": true,
+    "s3proxy": true,
+    "shibboleth": true
+  },
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306
+  },
+  "mappings": [
+    {
+      "local": "./",
+      "container": "/var/www/html/wp-content/plugins/bu-custom-analytics"
+    }
+  ],
+  "env": {
+    "WP_DEBUG": true
+  }
+}
+```
+
+Link or copy credentials:
+
+```bash
+# Option 1: Use Keychain (already global, nothing to do)
+
+# Option 2: Symlink to primary .env.local
+ln -s ~/projects/bu-sandbox-primary/.env.local .env.local
+```
+
+Add this plugin to the shared environment:
+
+```bash
+npx buwp-local start
+```
+
+Now your plugin is mounted into the shared WordPress instance!
+
+#### Add More Repositories
+
+Repeat for additional plugins/themes:
+
+```bash
+# Plugin B
+cd ~/projects/bu-slideshow
+npx buwp-local init --plugin
+# Edit .buwp-local.json with projectName: "bu-sandbox"
+npx buwp-local start
+
+# Theme
+cd ~/projects/responsive-framework
+npx buwp-local init --theme
+# Edit .buwp-local.json with projectName: "bu-sandbox"
+npx buwp-local start
+```
+
+### Accessing the Shared Environment
+
+All repositories share the same URL:
+
+```
+http://bu-sandbox.local
+```
+
+All plugins and themes are mounted:
+- `/wp-content/plugins/bu-custom-analytics/` → `~/projects/bu-custom-analytics/`
+- `/wp-content/plugins/bu-slideshow/` → `~/projects/bu-slideshow/`
+- `/wp-content/themes/responsive-framework/` → `~/projects/responsive-framework/`
+
+### Managing Shared Environments
+
+**Start the environment (from any repository):**
+
+```bash
+cd ~/projects/bu-custom-analytics
+npx buwp-local start
+```
+
+**Stop the environment (from any repository):**
+
+```bash
+cd ~/projects/bu-sandbox-primary
+npx buwp-local stop
+```
+
+**View logs (from any repository):**
+
+```bash
+cd ~/projects/bu-slideshow
+npx buwp-local logs -f
+```
+
+**Destroy and rebuild:**
+
+```bash
+cd ~/projects/bu-sandbox-primary
+npx buwp-local destroy
+npx buwp-local start
+```
+
+---
+
+## Configuration Consistency
+
+### ⚠️ Important: Keep Configs Synchronized
+
+All repositories sharing a `projectName` must have **matching configuration**:
+
+| Setting | Must Match | Why |
+|---------|-----------|-----|
+| `projectName` | ✅ Yes | Determines which project containers join |
+| `hostname` | ✅ Yes | All repos should access same URL |
+| `ports` | ✅ Yes | Port conflicts cause failures |
+| `services` | ✅ Yes | Enables/disables Redis, S3, Shibboleth |
+| `env` vars | ⚠️ Should | Avoid conflicting environment variables |
+| `mappings` | ❌ No | Each repo adds its own mappings |
+
+### Best Practices
+
+1. **Use primary repository as source of truth**
+   - Make configuration changes in primary repo
+   - Copy settings to secondary repos
+   - Document which repo is primary
+
+2. **Keep secondary repos minimal**
+   - Only add `mappings` section
+   - Copy all other settings from primary
+
+3. **Use symlinks for shared files**
+   ```bash
+   ln -s ~/projects/bu-sandbox-primary/.env.local .env.local
+   ```
+
+4. **Document the setup**
+   - Add README.md in primary repo
+   - List all participating repositories
+   - Note any special configuration
+
+---
+
+## Comparison: Isolated vs Shared
+
+| Aspect | Isolated | Shared |
+|--------|----------|--------|
+| **Use Case** | Solo development | Integration testing |
+| **Databases** | Separate per project | One shared database |
+| **WordPress** | Separate per project | One shared instance |
+| **URLs** | Different per project | Same for all repos |
+| **Ports** | Can differ | Must be identical |
+| **Data Isolation** | Complete | Shared |
+| **Setup Complexity** | Low | Medium |
+| **Best For** | Independent work | Team collaboration |
+
+### When to Use Isolated Environments
+
+✅ Developing one plugin/theme independently  
+✅ Need clean slate for testing  
+✅ Don't need other plugins active  
+✅ Want to test different WordPress versions  
+✅ Working on experimental features  
+✅ Need different PHP/MySQL settings per project
+
+### When to Use Shared Environments
+
+✅ Testing plugin interactions  
+✅ Developing theme + plugins together  
+✅ Mimicking production setup locally  
+✅ Team collaborating on same codebase  
+✅ Need persistent test data across plugins  
+✅ Integration/acceptance testing  
+✅ Want single URL for all development
+
+---
+
+## Troubleshooting
+
+### Port Conflicts
+
+**Problem:** Can't start second project due to port conflicts
+
+**Solution:** Use different ports in `.buwp-local.json`:
+
+```json
+{
+  "ports": {
+    "http": 8081,
+    "https": 8444,
+    "db": 3307
+  }
+}
+```
+
+### Shared Environment Config Drift
+
+**Problem:** Repos have different configurations causing issues
+
+**Solution:** Standardize configuration across all repos:
+
+1. Update primary repo with correct config
+2. Copy settings to all secondary repos
+3. Run `destroy` and `start` from primary
+
+### Can't Remove Plugin from Shared Environment
+
+**Problem:** Need to remove a plugin from shared WordPress
+
+**Solution:** Destroy and rebuild without that plugin:
+
+```bash
+cd ~/projects/bu-sandbox-primary
+npx buwp-local destroy
+
+# Don't start from the plugin you want to remove
+cd ~/projects/other-plugin
+npx buwp-local start
+```
+
+### Database Confusion
+
+**Problem:** Not sure which project's database you're using
+
+**Solution:** Check Docker volumes:
+
+```bash
+docker volume ls | grep db_data
+```
+
+Each isolated project has its own: `{projectName}_db_data`
+
+### Start Order Issues
+
+**Problem:** Last repo to start "wins" configuration
+
+**Solution:** Always start from primary repo first:
+
+```bash
+cd ~/projects/bu-sandbox-primary
+npx buwp-local start
+
+cd ~/projects/plugin-a
+npx buwp-local start
+```
+
+---
+
+## Advanced: Hybrid Approach
+
+You can use **both strategies** for different workflows:
+
+```bash
+# Isolated environment for experimentation
+cd ~/projects/bu-custom-analytics
+# .buwp-local.json has projectName: "bu-custom-analytics"
+npx buwp-local start
+# Test independently at http://bu-custom-analytics.local
+
+# Later: Test in shared environment
+# Edit .buwp-local.json, change projectName to "bu-sandbox"
+npx buwp-local start
+# Now part of shared sandbox at http://bu-sandbox.local
+
+# Switch back to isolated
+# Restore original projectName
+npx buwp-local destroy  # Clean up shared
+npx buwp-local start    # Back to isolated
+```
+
+**Tip:** Keep two config files:
+
+```bash
+.buwp-local.json           # Isolated (default)
+.buwp-local.shared.json    # Shared environment
+
+# Switch between them
+cp .buwp-local.shared.json .buwp-local.json  # Use shared
+cp .buwp-local.isolated.json .buwp-local.json  # Use isolated
+```
+
+---
+
+## See Also
+
+- [Getting Started](GETTING_STARTED.md) - Initial setup guide
+- [Commands Reference](COMMANDS.md) - Full command list
+- [Credentials Management](CREDENTIALS.md) - Managing credentials across projects
+- [Architecture](ARCHITECTURE.md) - Technical implementation details