my_openplace/DOCKER_PLUGINS_SETUP.md

Docker Plugin Setup - Summary of Changes

This document summarizes the changes made to ensure the plugin system works correctly in Docker.

Changes Made

1. Backend Route (src/routes/plugins.ts)

Problem: The route was hardcoded to use frontend-backup directory, which doesn't exist in Docker when USE_FRONTEND_BACKUP=false.

Solution: Updated to respect the USE_FRONTEND_BACKUP environment variable:

// Determine which frontend directory to use (matches index.ts logic)
const frontendDir = process.env['USE_FRONTEND_BACKUP'] === 'true' ? 'frontend-backup' : 'frontend';

2. Dockerfile

Problem: The plugins directory might not be created when building from source.

Solution: Updated the build step to ensure the plugins directory exists:

RUN if [ "$USE_FRONTEND_BACKUP" = "true" ]; then \
      rm -rf /app/frontend && mkdir -p /app/frontend && cp -R /app/frontend-backup/. /app/frontend/; \
    else \
      cd frontend-src && npm install && npm run build && \
      mkdir -p /app/frontend/plugins && \
      echo "Plugins directory created for frontend build"; \
    fi

3. Git Configuration

Created .gitignore in frontend-backup/plugins/ to:

• Keep the example plugin in version control
• Prevent user plugins from being committed
• Keep the README documentation

Testing in Docker

Option 1: Using Frontend Backup (Recommended for Development)

# Build with frontend-backup (includes SDK and example plugin)
docker build --build-arg USE_FRONTEND_BACKUP=true -t furryplace .

# Run
docker run -p 3000:3000 -e USE_FRONTEND_BACKUP=true furryplace

Option 2: Building from Source

# Build from source (requires frontend-src directory)
docker build --build-arg USE_FRONTEND_BACKUP=false -t furryplace .

# Run
docker run -p 3000:3000 -e USE_FRONTEND_BACKUP=false furryplace

Option 3: Runtime Plugin Mounting

# Mount plugins directory at runtime
docker run -d \
  -p 3000:3000 \
  -v ./my-plugins:/app/frontend/plugins \
  -e USE_FRONTEND_BACKUP=false \
  furryplace

Verification Steps

1. Build the image: docker build --build-arg USE_FRONTEND_BACKUP=true -t furryplace .
2. Run the container: docker run -p 3000:3000 -e USE_FRONTEND_BACKUP=true furryplace
3. Open browser: Navigate to http://localhost:3000
4. Check console: Should see:

   [FurryPlace SDK] Loaded v1.0.0
   [FurryPlace SDK] Auto-discovering plugins...
   [FurryPlace SDK] Found 1 plugin(s): ['example-button.js']
   [FurryPlace SDK] Loaded plugin: example-button.js
   

5. Test API: curl http://localhost:3000/api/plugins

   {
     "plugins": [
       {
         "name": "example-button.js",
         "path": "/plugins/example-button.js",
         "size": 12345,
         "modified": "2025-10-04T..."
       }
     ]
   }
   

File Structure in Container

When USE_FRONTEND_BACKUP=true:

/app/
├── dist/                    # Compiled backend
├── frontend/                # Frontend files (copied from frontend-backup)
│   ├── furryplace-sdk.js   # SDK file
│   ├── plugins/            # Plugins directory
│   │   ├── .gitignore
│   │   ├── README.md
│   │   └── example-button.js
│   ├── index.html          # (with SDK script tag injected)
│   └── ...
└── node_modules/

Environment Variables

Variable	Value	Effect
USE_FRONTEND_BACKUP	true	Uses frontend-backup/ directory (includes SDK)
USE_FRONTEND_BACKUP	false	Uses frontend/ directory (built from source)

Troubleshooting

Plugins not loading?

• Check that the plugins directory exists: docker exec <container> ls -la /app/frontend/plugins
• Check API response: curl http://localhost:3000/api/plugins
• Check container logs: docker logs <container>

SDK not found?

• Verify SDK was injected: docker exec <container> grep furryplace-sdk.js /app/frontend/index.html
• Check if file exists: docker exec <container> ls -la /app/frontend/furryplace-sdk.js

Wrong frontend directory?

• Verify environment variable: docker exec <container> env | grep USE_FRONTEND_BACKUP
• Check which directory is being used in logs

Next Steps

After verifying the setup works:

1. Add your custom plugins to frontend-backup/plugins/
2. Rebuild the Docker image
3. Deploy to production
4. Users will see the new buttons automatically!