1. Knowledge base
2. Deployment

Seatmap Helm chart documentation

Overview

The Seatmap Helm chart deploys the Seatmap.pro application stack: the Editor and Booking services, the converter service when converter.enabled is true, and the PostgreSQL and Redis dependencies.

• Chart version: the chart has no version of its own. Install it from the repository tag of the Seatmap version you deploy, for example 1.74.0.
• Application version: image tags default to latest. Set every image tag to that same version, so that the chart and all components run the same version.

Prerequisites

• Kubernetes 1.26+
• Helm 3.2.0+
• PV provisioner support in the underlying infrastructure
• LoadBalancer support (for ingress)

Dependencies

The chart includes the following Bitnami dependencies:

• PostgreSQL (version 12.x.x)
• Redis (version 17.x.x)

Installation

Installation from monorepo

The Helm chart is located at deployment/helm/seatmap/ in the monorepo. Check out the tag of the version you deploy, resolve the bitnami dependencies, and install:

git checkout ${SEATMAP_VERSION}
helm repo add bitnami https://charts.bitnami.com/bitnami
helm dependency update deployment/helm/seatmap

helm upgrade --install seatmap deployment/helm/seatmap \
  --create-namespace \
  --namespace seatmap \
  --set converter.enabled=true \
  --set global.hosts.editor=${EDITOR_HOST} \
  --set global.hosts.booking=${BOOKING_HOST} \
  --set-string editor.image.tag=${SEATMAP_VERSION} \
  --set-string editor.frontend.image.tag=${SEATMAP_VERSION} \
  --set-string booking.image.tag=${SEATMAP_VERSION} \
  --set-string booking.frontend.image.tag=${SEATMAP_VERSION} \
  --set-string converter.image.tag=${SEATMAP_VERSION} \
  --set global.s3.bucket=${S3_BUCKET} \
  --set global.s3.region=${S3_REGION} \
  --set global.s3.endpoint=${S3_ENDPOINT} \
  --set global.mail.host=${MAIL_HOST} \
  --set global.mail.fromAddress=${MAIL_FROM} \
  --set global.mail.port=${MAIL_PORT} \
  --set global.mail.strategy=${MAIL_STRATEGY} \
  --set-string secrets.s3.accessKey=${S3_ACCESS_KEY} \
  --set-string secrets.s3.secretKey=${S3_SECRET_KEY} \
  --set-string secrets.mail.username=${MAIL_USERNAME} \
  --set-string secrets.mail.password=${MAIL_PASSWORD} \
  --set-string secrets.google.apiKey=${GOOGLE_API_KEY} \
  --set imageCredentials.registry=${REGISTRY} \
  --set-string imageCredentials.username=${REGISTRY_USERNAME} \
  --set-string imageCredentials.password=${REGISTRY_PASSWORD}

Local testing

Run the full local stack test using kind:

./deployment/helm/test-local.sh

Configuration

Global parameters

Host Configuration

global:
  hosts:
    editor: editor.test-5.seatmap.dev
    booking: booking.test-5.seatmap.dev

Image Registry

imageCredentials:
  registry: registry.gitlab.com
  username: seatmap
  password: <password>

Resource configurations

Unless you set global.resources, the Editor, Booking and converter containers run without CPU or memory requests and limits. default applies to the Editor, Booking and converter services and frontend to both frontends. Each group you set needs all four values. The values below are a starting point:

global:
  resources:
    default:
      requests:
        cpu: '500m'
        memory: '2Gi'
      limits:
        cpu: '1000m'
        memory: '3Gi'
    frontend:
      requests:
        cpu: '100m'
        memory: '192Mi'
      limits:
        cpu: '1000m'
        memory: '512Mi'

Ingress configuration

The chart provides ingress configurations for both Editor and Booking services with separate hostnames.

Global ingress settings

global:
  ingress:
    className: public
    proxyBodySize: '50m'
    annotations:
      cert-manager.io/cluster-issuer: 'letsencrypt-prod'
  hosts:
    editor: editor.test-5.seatmap.dev
    booking: booking.test-5.seatmap.dev

Editor Ingress

The Editor service ingress is configured to handle both web and API traffic on its dedicated domain.

editor:
  ingress:
    enabled: true
    annotations: {} # Additional service-specific annotations
    apiPaths:
      - /api
      - /swagger-ui
      - /preview
      - /media
      - /ws
      - /webjars
      - /v3

Features:

• Host: editor.{domain} (e.g., editor.test-5.seatmap.dev)
• TLS enabled with hostname-based certificate
• Default web path (/) routes to web port
• API paths route to API port
• WebSocket support enabled
• Configurable max body size

Booking Ingress

The Booking service ingress is configured on its own dedicated domain.

booking:
  ingress:
    enabled: true
    annotations: {} # Additional service-specific annotations
    apiPaths:
      - /api
      - /swagger-ui
      - /custom
      - /scalar
      - /scalar.html
      - /scalar-v1.html
      - /scalar-v2-booking.html
      - /scalar-v2-management.html
      - /webjars
      - /v3
      - /csrf
      - /oauth2
      - /login
      - /.well-known

Features:

• Host: booking.{domain} (e.g., booking.test-5.seatmap.dev)
• TLS enabled with hostname-based certificate
• Default web path (/) routes to web port
• API paths route to API port
• WebSocket support enabled
• Shared proxy body size configuration with Editor

Common ingress features

Both ingresses include:

• NGINX annotations for body size limits
• WebSocket support
• TLS configuration
• Implementation-specific path types for root paths
• Prefix path types for API endpoints

Component configurations

PostgreSQL

• Authentication managed through postgresql-secret
• Default database and username: seatmap
• Includes uuid-ossp extension initialization

postgresql:
  enabled: true
  auth:
    existingSecret: 'postgresql-secret'
    username: seatmap
    database: seatmap

Redis

• Standalone architecture
• Authentication enabled through redis-secret
• Memory configuration:
  • Max memory: 512MB
  • Policy: allkeys-lru

redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: true
    existingSecret: 'redis-secret'
  master:
    persistence:
      enabled: true
      size: 8Gi

Container registry

All service images are hosted on the GitLab Container Registry:

Image tags follow semantic versioning (e.g., 1.74.0 for releases, 1.75.0-dev.18-939ed1ec for dev/stage builds).

Service components

Editor service

editor:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/editor-service
    tag: '1.74.0'
  frontend:
    image:
      repository: registry.gitlab.com/seatmap.pro/seatmap/editor-client
      tag: '1.74.0'

Key configurations:

• HikariCP connection pool settings
• Token expiration settings
• SSO integration support
• API paths for ingress

Booking service

booking:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/booking-service
    tag: '1.74.0'
  frontend:
    image:
      repository: registry.gitlab.com/seatmap.pro/seatmap/booking-client
      tag: '1.74.0'

Features:

• JPA/Hibernate configuration
• Connection pool settings
• OAuth2 support
• Actuator endpoints

Converter service

converter:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/converter-service
    tag: '1.74.0'

converter:
  config:
    async:
      enabled: true
      cpuClaimDelayMs: 5000
    rateLimit:
      jobsMax: 5000
  gpu:
    enabled: false

Behaviour:

• The chart deploys the converter only when converter.enabled is true, as in the install command above.
• Conversions are queued in the release’s Redis while converter.config.async.enabled is true (the default). Set it to false to render inside the request without Redis.
• converter.gpu.enabled adds a GPU pod variant that claims queued jobs first; the CPU pods pick up whatever it does not take.
• With converter.enabled set, the chart generates a shared secret in <release>-converter and wires it into editor-service. A deployment that runs the converter in a separate release leaves converter.enabled off, points editor.converter at that converter’s URL, and sets the same secrets.converter.apiKey on both sides before upgrading either.

Limitations:

• Max content length: 32MB
• Max image dimensions: 15000x15000 pixels
• S3 storage integration

External service configuration

S3 storage

global:
  s3:
    bucket: 'seatmap-storage'
    region: 'us-east-1'
    endpoint: 'https://s3.amazonaws.com'

Mail server

global:
  mail:
    host: 'smtp.example.com'
    port: 587
    strategy: 'SMTP_TLS'
    fromAddress: 'seatmap@example.com'

Password reset email stays off until host and fromAddress are set. strategy takes SMTPS for implicit TLS, usually on port 465, SMTP_TLS for STARTTLS, usually on port 587, or SMTP, which sends unencrypted when the server does not offer STARTTLS and suits only a trusted network; the chart refuses any other value. Left empty, the editor uses SMTPS on port 465 and SMTP_TLS on any other port. Leave secrets.mail.username and secrets.mail.password empty when the mail server accepts mail without signing in.

Security considerations

JWT signing keys

The editor service signs its tokens with an RSA keypair held in the {release}-rsa Secret. A pre-install and pre-upgrade hook creates it and never overwrites an existing one, so the keypair survives every upgrade and issued tokens keep verifying.

The hook migrates existing key material into the Secret verbatim on upgrade – no token is invalidated and no user is signed out. If the existing key data is empty the hook refuses to migrate and fails the upgrade, rather than silently generating a new keypair and invalidating every live session.

A new keypair is generated only on a fresh install, where there is nothing to carry over.

Once the upgrade succeeds you can delete the old ConfigMap. Nothing reads it any more.

kubectl delete configmap {release}-rsa -n {namespace}

Secrets management

The following secrets must be provided:

• PostgreSQL credentials
• Redis password
• S3 access credentials
• Mail server credentials, when the mail server requires sign-in
• Google API key
• Converter shared secret (generated by the chart when converter.enabled is true, or secrets.converter.apiKey for a split release)

Network security

• TLS termination through ingress
• cert-manager integration for automated certificate management
• Separate API and web ports for services

Scaling

Horizontal pod autoscaling

Each service has its own autoscaler switch, off by default: editor.hpa.enabled, booking.hpa.enabled and converter.hpa.enabled. These targets apply to all three:

global:
  hpa:
    targetCPUUtilizationPercentage: 80
    targetMemoryUtilizationPercentage: 80

The autoscalers measure utilization against the containers’ requests, so set global.resources before you enable them.

Replica ranges (*.hpa.minReplicas and *.hpa.maxReplicas):

• Editor: 2-6 replicas
• Booking: 2-6 replicas
• Converter: 1-4 replicas

Monitoring and metrics

• Actuator endpoints enabled for Spring Boot services
• Redis metrics disabled by default
• Custom metrics endpoints configured for editor and booking services

Troubleshooting

Common issues

1. Image pull errors

   • Verify registry credentials
   • Check image tags exist

2. Database connection issues

   • Verify PostgreSQL secret exists
   • Check connection pool settings

3. Storage issues

   • Validate S3 credentials and bucket accessibility
   • Check storage quotas and limits

Debugging

1. Access logs through:

   kubectl logs -f deployment/seatmap-<component>
   

2. Check service status:

   kubectl get pods -l app.kubernetes.io/instance=seatmap
   

Configuration variables reference

Global variables

Instance variables

PostgreSQL variables

Redis variables

Editor service variables

Booking service variables

Converter service variables

External service variables

Support and maintenance

• Regular updates through version tags
• Configuration changes through Helm upgrade
• Persistent storage management for PostgreSQL and Redis