1. Knowledge base
2. Deployment

Image Converter Configuration Guide

The image converter is a Node.js microservice that renders SVG venue backgrounds into optimized WebP images. It produces three variants per background – full resolution, a 1000px preview, and a 400px blurred placeholder with inline base64 data for progressive loading. Images are stored in S3-compatible object storage or on the local filesystem.

Stack: Node.js 22, Express 5, Puppeteer (headless Chromium for SVG rendering), Sharp (image processing), Redis (conversion queue).

Core settings

File handling settings

Image processing settings

Storage settings

AWS S3 configuration

These settings are required when STORAGE_TYPE=s3.

ImportantAWS credentials should be provided through secure environment variables or Kubernetes secrets. Never commit credentials to version control.

Public URL resolution

The converter generates public URLs for uploaded images. The URL base is resolved in this priority order:

1. AWS_PUBLIC_BASE_URL (if set) – used as-is. Example: https://bucket.nyc3.digitaloceanspaces.com
2. AWS_ENDPOINT_URL (derived) – path-style: {endpoint}/{bucket}. Example: https://storage.yandexcloud.net/my-bucket
3. Default – AWS virtual-hosted style: https://{bucket}.s3.{region}.amazonaws.com

Self-hosted customers using non-AWS S3 providers (DigitalOcean Spaces, MinIO, Garage, Yandex Cloud) should set AWS_PUBLIC_BASE_URL to ensure correct public URLs.

S3 bucket policy

To allow public read access to images, apply the following bucket policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

CORS configuration

To prevent tainted canvas issues when processing images in web browsers, configure CORS on the bucket:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": []
  }
]

NoteFor production environments, restrict AllowedOrigins to your specific domains instead of *.

Redis settings

Conversions are queued in Redis when REDIS_ENABLED=true (the Helm chart default). Each request is recorded as a job; a converter with a GPU claims it first, a CPU converter claims it after CPU_CLAIM_DELAY_MS, and a job whose worker dies mid-render is returned to the queue and retried. With REDIS_ENABLED=false the converter renders inside the request and needs no Redis. While Redis is enabled but unreachable the converter also renders inside the request, answers 503 on GET /jobs/{id} and logs connection errors; queueing starts on its own once Redis is reachable.

Authentication

API endpoints

POST /, /background/ and /thumbnail/ accept multipart/form-data with an SVG file (image/svg+xml). POST /photo/ accepts a JPEG, PNG or WebP file up to 10 MB and answers with url and thumbUrl.

With queueing enabled, a conversion route answers 202 Accepted with a job id and the result is read from GET /jobs/{id}; editor-service does this polling itself. With queueing disabled the routes answer with the result directly.

Rate limiting: RATE_LIMIT_MAX requests (default 600) per RATE_LIMIT_WINDOW_MS (default 60000) per IP address on the conversion routes, /photo/ included. GET /jobs/{id} has its own budget, JOBS_RATE_LIMIT_MAX requests per minute (default 5000). /health and /metrics are not throttled.

Request timeout: 5 minutes (300 seconds).

Output format

The converter generates WebP images (not PNG), providing 30-50% smaller file sizes with alpha channel support.

Three variants are produced for each background:

Files are stored at backgrounds/{filename}/{variant}.webp in the configured storage backend.

Docker

The service runs in a Docker container based on node:22.14.0-alpine with Chromium installed for Puppeteer.

Port: 3000

Health check: GET /health every 30 seconds (3 retries, 5-second start period)

Environment variables for Puppeteer:

• PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true (uses system Chromium)
• PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

Security: Runs as non-root user (uid 10001). Uses tini as init process to prevent zombie processes.

Monitoring

Prometheus metrics

The /metrics endpoint exposes:

• http_request_duration_seconds – histogram with method, route, status_code labels
• http_requests_total – counter with method, route, status_code labels
• Default Node.js process metrics (memory, CPU, event loop lag, GC)

Metric buckets are optimized for image processing workloads: 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30 seconds.

Health endpoints

• GET /health – returns 200 if the service is running
• GET /health/redis – returns Redis connection status, the pod’s conversion role, and the pending and processing queue depths

Configuration methods

The application can be configured through multiple methods listed in order of precedence:

1. Environment variables
2. Kubernetes ConfigMap/Secrets
3. .env file (development only)

Kubernetes deployment

When deploying to Kubernetes, configuration is managed through Helm values and secrets:

converter:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/converter-service
    tag: latest
  env:
    PORT: '3000'
    LOG_LEVEL: 'info'
    STORAGE_TYPE: 's3'
    AWS_REGION: 'us-east-1'
    AWS_BUCKET_NAME: 'your-bucket'
    # AWS_PUBLIC_BASE_URL: "https://your-cdn.example.com"  # if using non-AWS S3

Secrets management

AWS credentials and Redis passwords should be managed securely using one of these methods:

• Kubernetes Secrets (injected via seatmap-helm-secrets)
• External Secrets Operator
• IAM roles for Service Accounts (IRSA)

Development setup

For local development using Docker Compose:

cd products/converter-service
cp .env.sample .env
# Edit .env with your settings (use STORAGE_TYPE=local for development)
docker compose up

This starts the converter service on port 3000 and a Redis instance on port 6379.

Never commit sensitive credentials to version control.

Troubleshooting

Common configuration issues:

• Image upload fails: Check MAX_CONTENT_LENGTH and ingress body-size configuration. The default 16 MB limit may need increasing for large SVG files.
• S3 access denied: Verify AWS credentials and bucket permissions. Check that AWS_PUBLIC_BASE_URL matches your actual bucket URL scheme.
• Blank or corrupted images: Verify Chromium is installed (/usr/bin/chromium-browser). In Docker, ensure the PUPPETEER_EXECUTABLE_PATH environment variable is set correctly.
• High memory usage: Sharp and Puppeteer can consume significant memory with large SVG files. Set container memory limits to at least 512 MB, with 2 GB recommended for production.
• WebP not loading in renderer: Ensure CORS headers are configured on the S3 bucket. The renderer needs cross-origin access to load background images.
• Wrong public URLs: If using a non-AWS S3 provider, set AWS_PUBLIC_BASE_URL explicitly. The default URL generation assumes AWS virtual-hosted bucket style.