1. Base de conocimiento
2. Despliegue

Guía de configuración de Image Converter

Image converter es un microservicio de Node.js que renderiza fondos SVG de recintos en imágenes WebP optimizadas. Produce tres variantes por cada fondo: resolución completa, una previsualización de 1000px y un marcador de posición difuminado de 400px con datos base64 incorporados para la carga progresiva. Las imágenes se almacenan en almacenamiento de objetos compatible con S3 o en el sistema de archivos local.

Stack: Node.js 22, Express 5, Puppeteer (Chromium headless para renderizar SVG), Sharp (procesamiento de imágenes), Redis opcional (cola asíncrona de resultados).

Ajustes principales

Ajustes de manejo de archivos

Ajustes de procesamiento de imágenes

Ajustes de almacenamiento

Configuración de AWS S3

Estos ajustes son obligatorios cuando STORAGE_TYPE=s3.

ImportantLas credenciales de AWS deben proporcionarse mediante variables de entorno seguras o secretos de Kubernetes. Nunca incluyas credenciales en el control de versiones.

Resolución de la URL pública

El conversor genera URL públicas para las imágenes subidas. La base de la URL se resuelve en este orden de prioridad:

1. AWS_PUBLIC_BASE_URL (si está definida) — se usa tal cual. Ejemplo: https://bucket.nyc3.digitaloceanspaces.com
2. AWS_ENDPOINT_URL (derivada) — path-style: {endpoint}/{bucket}. Ejemplo: https://storage.yandexcloud.net/my-bucket
3. Por defecto — estilo virtual-hosted de AWS: https://{bucket}.s3.{region}.amazonaws.com

Los clientes self-hosted que usan proveedores de S3 distintos de AWS (DigitalOcean Spaces, MinIO, Garage, Yandex Cloud) deben definir AWS_PUBLIC_BASE_URL para garantizar URL públicas correctas.

Política del bucket de S3

Para permitir el acceso público de lectura a las imágenes, aplica la siguiente política de bucket:

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

Configuración de CORS

Para evitar problemas de tainted canvas al procesar imágenes en navegadores web, configura CORS en el bucket:

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

NotePara entornos de producción, restringe AllowedOrigins a tus dominios específicos en lugar de *.

Ajustes de Redis

Redis es opcional. Cuando está activado, los resultados de la conversión se envían a una cola de Redis para su procesamiento asíncrono por otros servicios.

Si Redis está desactivado o no disponible, las conversiones igualmente se completan con éxito: la publicación en la cola no es bloqueante.

Endpoints de la API

Todos los endpoints POST aceptan multipart/form-data con un archivo SVG. Los archivos deben tener la extensión .svg y el tipo MIME image/svg+xml.

Limitación de tasa: 30 solicitudes cada 60 segundos por dirección IP.

Tiempo de espera de la solicitud: 5 minutos (300 segundos).

Formato de salida

El conversor genera imágenes WebP (no PNG), lo que proporciona archivos un 30-50% más pequeños con soporte de canal alfa.

Se producen tres variantes para cada fondo:

Los archivos se almacenan en backgrounds/{filename}/{variant}.webp en el backend de almacenamiento configurado.

Docker

El servicio se ejecuta en un contenedor Docker basado en node:22.14.0-alpine con Chromium instalado para Puppeteer.

Puerto: 3000

Comprobación de estado: GET /health cada 30 segundos (3 reintentos, período de inicio de 5 segundos)

Variables de entorno para Puppeteer:

• PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true (usa el Chromium del sistema)
• PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

Seguridad: Se ejecuta como usuario non-root (uid 10001). Usa tini como proceso init para evitar procesos zombie.

Monitorización

Métricas de Prometheus

El endpoint /metrics expone:

• http_request_duration_seconds — histograma con etiquetas method, route, status_code
• http_requests_total — contador con etiquetas method, route, status_code
• Métricas por defecto del proceso de Node.js (memoria, CPU, latencia del event loop, GC)

Los buckets de métricas están optimizados para cargas de procesamiento de imágenes: 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30 segundos.

Endpoints de estado

• GET /health — devuelve 200 si el servicio está en ejecución
• GET /health/redis — devuelve el estado de la conexión con Redis, el nombre de la cola y la longitud de la cola

Métodos de configuración

La aplicación se puede configurar mediante varios métodos, enumerados en orden de prioridad:

1. Variables de entorno
2. Kubernetes ConfigMap/Secrets
3. Archivo .env (solo para desarrollo)

Despliegue en Kubernetes

Al desplegar en Kubernetes, la configuración se gestiona mediante valores de Helm y secretos:

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

Gestión de secretos

Las credenciales de AWS y las contraseñas de Redis deben gestionarse de forma segura mediante uno de estos métodos:

• Kubernetes Secrets (inyectados a través de seatmap-helm-secrets)
• External Secrets Operator
• IAM roles for Service Accounts (IRSA)

Configuración para desarrollo

Para el desarrollo local usando Docker Compose:

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

Esto inicia el servicio del conversor en el puerto 3000 y una instancia de Redis en el puerto 6379.

Nunca incluyas credenciales sensibles en el control de versiones.

Resolución de problemas

Problemas de configuración comunes:

• Fallo al subir la imagen: Comprueba MAX_CONTENT_LENGTH y la configuración del tamaño del cuerpo en el ingress. El límite por defecto de 16 MB puede necesitar un aumento para archivos SVG grandes.
• Acceso denegado a S3: Verifica las credenciales de AWS y los permisos del bucket. Comprueba que AWS_PUBLIC_BASE_URL coincide con el esquema de URL real de tu bucket.
• Imágenes en blanco o corruptas: Verifica que Chromium esté instalado (/usr/bin/chromium-browser). En Docker, asegúrate de que la variable de entorno PUPPETEER_EXECUTABLE_PATH esté configurada correctamente.
• Uso elevado de memoria: Sharp y Puppeteer pueden consumir mucha memoria con archivos SVG grandes. Establece límites de memoria del contenedor de al menos 512 MB, con 2 GB recomendados para producción.
• WebP no se carga en el renderer: Asegúrate de que las cabeceras CORS estén configuradas en el bucket de S3. El renderer necesita acceso de origen cruzado para cargar las imágenes de fondo.
• URL públicas incorrectas: Si usas un proveedor de S3 distinto de AWS, define AWS_PUBLIC_BASE_URL de forma explícita. La generación de URL por defecto asume el estilo de bucket virtual-hosted de AWS.