puffinOffsetCalculator/README.docker.md

# Puffin Offset Calculator Docker Setup

This guide explains how to containerize the Puffin Offset Calculator app, push it to a Gitea container registry, and embed it into your WordPress website.

## Files Overview

- `Dockerfile` - Defines how to build the Docker image for the React app
- `docker-compose.yml` - Orchestrates the container deployment, pulling the image from Gitea registry
- `nginx.conf` - Configures Nginx to serve the React app correctly
- `wordpress-integration.php` - WordPress plugin file for embedding the calculator
- `setup.sh` - Script to automate the container deployment process including Gitea login
- `gitea-image-push.sh` - Script to build and push the Docker image to Gitea registry
- `puffin-calculator.css` - Styling for the WordPress integration
- `puffin-calculator.js` - JavaScript for the WordPress integration

## Workflow Overview

The workflow to deploy the Puffin Offset Calculator consists of two main stages:

1. **Build and Push Stage**: Build the Docker image and push it to the Gitea container registry
2. **Deployment Stage**: Pull the image from the registry and run it on your server

## Getting Started

### Prerequisites

- Docker and Docker Compose installed on your development machine and server
- Gitea repository access with container registry enabled
- WordPress website where you want to embed the calculator
- Basic knowledge of Docker and WordPress

### Step 1: Build and Push the Docker Image

1. Place the `Dockerfile`, `nginx.conf`, and `gitea-image-push.sh` files in the project root directory.

2. Make the image push script executable:
   ```bash
   chmod +x gitea-image-push.sh
   ```

3. Run the script to build and push the image:
   ```bash
   ./gitea-image-push.sh
   ```
   
   This script will:
   - Prompt you to log in to the Gitea registry
   - Build the Docker image using the Dockerfile
   - Push the built image to the Gitea registry

### Step 2: Deploy the Container

1. Place the `docker-compose.yml`, `nginx.conf`, and `setup.sh` files in a directory on your server.

2. Make the setup script executable:
   ```bash
   chmod +x setup.sh
   ```

3. Run the setup script:
   ```bash
   ./setup.sh
   ```
   
   This script will:
   - Create a logs directory
   - Check if Docker and Docker Compose are installed
   - Prompt you to log in to the Gitea registry
   - Pull and start the Docker container

4. Verify the container is running:
   ```bash
   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