first commit
This commit is contained in:
Frank John Begornia
219
README.md
Normal file
219
README.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user