screenshot-tools/README.md

# Screenshot Service

Unified Node.js service for generating merchandise design screenshots using Puppeteer.

## Overview

This service consolidates multiple screenshot generation endpoints that were previously running on separate ports. It now provides a single, well-organized application with proper routing.

## Architecture

```
nodejs/
├── server.js              # Main application entry point
├── config/
│   └── config.js         # Configuration (SSL, CORS, URLs)
├── middleware/
│   └── cors.js           # CORS middleware
├── routes/
│   ├── jersey.js         # Jersey screenshot routes
│   ├── tshirt.js         # T-Shirt screenshot routes
│   ├── merchbay.js       # Merchbay screenshot routes
│   └── mask.js           # Mask screenshot routes
├── utils/
│   └── screenshot.js     # Screenshot utility functions
└── package.json          # Dependencies and scripts
```

## Installation

```bash
npm install
```

## Configuration

### Environment Variables

Create a `.env` file from the example:
```bash
cp .env.example .env
```

Key configuration options:
- `USE_SSL=false` - Use HTTP (recommended for Traefik deployment)
- `USE_SSL=true` - Use HTTPS with direct SSL certificates
- `PORT=5955` - Server port
- `BASE_URL` - Base URL for generated screenshot links

### Traefik Deployment (Recommended)

When deploying behind Traefik with automatic SSL:
1. Set `USE_SSL=false` in your `.env` file
2. The app will run on HTTP
3. Traefik handles SSL termination with automatic Let's Encrypt certificates
4. No SSL certificate files needed

### Direct SSL Deployment

If deploying without a reverse proxy:
1. Set `USE_SSL=true` in your `.env` file
2. Configure SSL certificate paths:
   - `SSL_KEY_PATH=/path/to/key.pem`
   - `SSL_CERT_PATH=/path/to/cert.pem`

## Usage

### Development
```bash
npm run dev
```

### Production
```bash
npm start
```

## API Endpoints

### Health Check
- `GET /health` - Service health status

### Jersey Screenshots
- `GET /jersey/:designId` - Generate 4-view screenshots (front, back, right, left)

### T-Shirt Screenshots
- `GET /tshirt/:designId` - Generate 4-view screenshots
- `GET /tshirt/allover/:designId` - Generate 2-view all-over print screenshots

### Merchbay Screenshots
- `GET /merchbay/tshirt/:designId` - Generate 4-view screenshots
- `GET /merchbay/allover/:designId` - Generate 2-view all-over print screenshots
- `GET /merchbay/legacy/:designId` - Legacy viewer URL format (4 views)

### Mask Screenshots
- `GET /mask/:designId` - All-over print mask (single view)
- `GET /mask/classic/:designId` - Classic mask (single view, larger)

### Legacy Routes (Backwards Compatible)
- `GET /tb/:designId` → Maps to `/jersey/:designId`
- `GET /ap/:designId` → Maps to `/tshirt/allover/:designId`

## Response Format

All endpoints return JSON/JSONP with the following structure:

```json
{
  "thumb_front": "https://crewsportswear.app:5955/designId-front-thumbnail.png",
  "thumb_back": "https://crewsportswear.app:5955/designId-back-thumbnail.png",
  "thumb_right": "https://crewsportswear.app:5955/designId-right-thumbnail.png",
  "thumb_left": "https://crewsportswear.app:5955/designId-left-thumbnail.png",
  "time": "2025-12-23T12:00:00.000Z"
}
```

## Features

- ✅ **Unified Application**: Single server instead of multiple separate services
- ✅ **Organized Routes**: Clean route structure with dedicated modules
- ✅ **CORS Support**: Configured allowed origins
- ✅ **Caching**: Checks for existing screenshots before regenerating
- ✅ **Error Handling**: Proper error handling and logging
- ✅ **Backwards Compatibility**: Legacy routes still work
- ✅ **HTTPS**: SSL/TLS support
- ✅ **Health Check**: Monitoring endpoint
- ✅ **Graceful Shutdown**: Proper cleanup on termination

## Configuration

Edit `config/config.js` to modify:
- SSL certificate paths
- Allowed CORS origins
- Screenshot output directory
- Base URL for generated images
- Viewport dimensions
- Wait times
- Viewer URLs

## Migration from Old Services

### Before (Multiple Services)
```
jersey-screenshot.js   → Port 5951
merchbay-tshirt.js    → Port 5952
tshirt_ss.js          → Port 5952
mask.js               → Port 5953
```

### After (Single Unified Service)
```
server.js → Port 5955 (configurable)
All routes available on the same port
```

### Updating Laravel Applications

Update your `.env` or configuration to point to the new unified service:

```env
IMAGES_URL=https://your-domain:5955
```

Then update API calls:
- Old: `https://domain:5951/tb/:designId`
- New: `https://domain:5955/jersey/:designId` (or use legacy route `/tb/:designId`)

## Logging

The service logs:
- Route access
- Screenshot generation status
- Errors and exceptions
- Server startup information

## Environment Variables

### Server
- `PORT` - Server port (default: 5955)
- `HOST` - Server host (default: 0.0.0.0)
- `USE_SSL` - Enable direct SSL (true/false, default: false)

### SSL (only when USE_SSL=true)
- `SSL_KEY_PATH` - Path to SSL private key
- `SSL_CERT_PATH` - Path to SSL certificate

###Deployment Options

### Option 1: Traefik with Auto SSL (Recommended)
1. Set `USE_SSL=false`
2. Configure Traefik labels in docker-compose
3. Traefik handles SSL with Let's Encrypt
4. App runs on HTTP internally

### Option 2: Direct SSL
1. Set `USE_SSL=true`
2. Provide SSL certificates:
   - Key: `/etc/httpd/ssl/crewsportswear_app.key`
   - Cert: `/etc/httpd/ssl/certs/current_cert.crt`
3. App runs on HTTPS directlydefault: 1100)
- `WAIT_TIME` - Wait time before screenshot in ms (default: 10000)

## Dependencies

- **express**: Web framework
- **puppeteer**: Headless browser for screenshots
- **nodemon**: Development auto-reload (dev dependency)

## SSL Certificates

Ensure SSL certificates are available at:
- Key: `/etc/httpd/ssl/crewsportswear_app.key`
- Cert: `/etc/httpd/ssl/certs/current_cert.crt`

## Notes

- Screenshots are cached in `/var/www/html/images/`
- If a screenshot already exists, it returns immediately without regeneration
- All routes support JSONP for cross-domain compatibility
- Puppeteer runs in headless mode with `--no-sandbox` for Docker compatibility