puffinOffsetCalculator/README.docker.md

Puffin Offset Calculator Docker Setup

This guide explains how to containerize the Puffin Offset Calculator app and embed it into your WordPress website.

Files Overview

• Dockerfile - Defines how to build the Docker image for the React app
• nginx.conf - Configures Nginx to serve the React app correctly
• docker-compose.yml - Orchestrates the container deployment
• wordpress-integration.php - WordPress plugin file for embedding the calculator

Getting Started

Prerequisites

• Docker and Docker Compose installed on your server
• WordPress website where you want to embed the calculator
• Basic knowledge of Docker and WordPress

Step 1: Build and Run the Docker Container

1. Place the Dockerfile, nginx.conf, and docker-compose.yml files in the project root directory (where your React app code is located).

2. Create a logs directory for storing Nginx logs:

   mkdir logs
   

3. Build and start the container:

   docker-compose up -d
   

4. Verify the container is running:

   docker ps
   

Your calculator should now be accessible at http://localhost:8080.

Step 2: Configure for Production (Optional)

For production deployment, update the docker-compose.yml file:

1. Change the port if needed (e.g., if you have other services using port 8080)
2. Remove the development volume mounts
3. Set up any environment variables needed for your production environment

Step 3: Install WordPress Plugin

1. Create a new directory in your WordPress plugins folder:

   wp-content/plugins/puffin-offset-calculator/
   

2. Copy the wordpress-integration.php file to this directory.

3. Create the CSS and JS directories in the plugin folder:

   wp-content/plugins/puffin-offset-calculator/css/
   wp-content/plugins/puffin-offset-calculator/js/
   

4. Create empty placeholder files for CSS and JS:

   touch wp-content/plugins/puffin-offset-calculator/css/puffin-calculator.css
   touch wp-content/plugins/puffin-offset-calculator/js/puffin-calculator.js
   

5. Activate the plugin in your WordPress admin panel.

Step 4: Embed the Calculator

You have two ways to embed the calculator:

Option 1: Using the Shortcode

Add the shortcode to any page or post:

[puffin_calculator]

You can customize the appearance:

[puffin_calculator height="600px" width="100%" url="http://your-server-ip:8080"]

Option 2: Using the Widget

1. Go to Appearance > Widgets in your WordPress admin.
2. Drag the "Puffin Offset Calculator" widget to your desired widget area.
3. Configure the widget settings (title, height, and URL).

Troubleshooting

Calculator Not Loading

• Check if the Docker container is running: docker ps
• Verify you can access the calculator directly at http://localhost:8080
• Check Nginx logs: docker-compose logs puffin-calculator
• Ensure your WordPress site can reach the Docker container (especially important if they're on different servers)

CORS Issues

If you see CORS errors in your browser console, check that:

• The Nginx configuration is correctly allowing cross-origin requests
• Your WordPress site is using HTTPS but trying to embed an HTTP iframe (Mixed content blocking)

Advanced Configuration

Custom Domain

To use a custom domain for your calculator:

1. Update your DNS to point to your server
2. Modify nginx.conf:

   server_name your-calculator-domain.com;
   

3. Set up SSL with Let's Encrypt
4. Update the URL in your WordPress shortcode or widget

SSL Setup

For production, you should secure your calculator with SSL:

1. Use a reverse proxy like Traefik or Nginx Proxy Manager
2. Configure Let's Encrypt for automatic certificate generation
3. Update your docker-compose.yml to work with your chosen SSL solution

Communication Between WordPress and the Calculator

For advanced integration where WordPress needs to exchange data with the calculator:

• Use postMessage API for iframe communication
• Implement message handling in both WordPress and the React app
• Add custom JS in the WordPress plugin's js file to facilitate this communication