Manual Mapas - Kubernetes com Helm

Deploy Mapas Culturais em produção usando o Helm chart oficial em um cluster Kubernetes.

O Helm chart do Mapas Culturais faz o deploy da plataforma completa, incluindo aplicação, PostgreSQL/PostGIS e Redis, em qualquer cluster Kubernetes. A imagem de contêiner é publicada em ghcr.io/redemapas/mapas.

Pré-requisitos

kubectl configurado para o cluster de destino
Helm 3.x instalado
cluster com ao menos 512Mi de memória disponível por pod

Instalação rápida

helm install mapas ./helm/mapas \
  --set postgresql.settings.superuserPassword=$(openssl rand -base64 32)

Isso instala o Mapas Culturais com:

subchart interno de PostgreSQL/PostGIS
duas instâncias internas de Redis, uma para cache e outra para sessões
PersistentVolumeClaims para assets, arquivos públicos e arquivos privados

Modos de configuração do Redis

O chart suporta estes modos de Redis:

Modo	Comando
Redis interno (padrão)	`helm install mapas ./helm/mapas`
Redis externo com senha	`helm install mapas ./helm/mapas -f helm/mapas/values-dev.yaml`
Sem Redis (filesystem/APCu)	`--set redis-cache.enabled=false --set redis-sessions.enabled=false`
Redis único para cache + sessões	`--set mapas.useSameRedisForCacheAndSessions=true`

Exemplo de Redis externo

mapas:
  redisCache:
    host: "my-redis.default.svc.cluster.local"
    port: 6379
    existingSecret: "redis-secret"
    existingSecretKey: "password"

  redisSessions:
    host: "my-redis.default.svc.cluster.local"
    port: 6379
    existingSecret: "redis-secret"
    existingSecretKey: "password"

redis-cache:
  enabled: false

redis-sessions:
  enabled: false

Referência das principais values

Aplicação

Value	Padrão	Descrição
`mapas.appEnv`	`production`	Ambiente de execução
`mapas.appDebug`	`false`	Ativa modo debug
`mapas.numProcesses`	`2`	Processos PHP workers
`mapas.jobsInterval`	`60`	Intervalo dos jobs em segundo
`mapas.buildAssets`	`0`	Compila assets do frontend no boot

Banco de dados

Value	Descrição
`mapas.database.host`	Host do banco externo (quando `postgresql.enabled: false`)
`mapas.database.port`	Porta do banco (padrão: 5432)
`mapas.database.name`	Nome do banco
`mapas.database.user`	Usuário do banco
`mapas.database.existingSecret`	Secret do Kubernetes com a senha do banco

Cache Redis

Value	Descrição
`mapas.redisCache.host`	Host do Redis (vazio = usa fallback em APCu/filesystem)
`mapas.redisCache.port`	Porta do Redis (padrão: 6379)
`mapas.redisCache.password`	Senha inline
`mapas.redisCache.existingSecret`	Nome do secret no K8s
`mapas.redisCache.existingSecretKey`	Chave dentro do secret (padrão: `password`)

Sessões Redis

Mesma estrutura de redisCache. Defina mapas.useSameRedisForCacheAndSessions: true para compartilhar uma única instância Redis.

Mailer

Value	Padrão	Descrição
`mapas.mailer.transport`	`smtp://localhost:25`	DSN do Symfony Mailer
`mapas.mailer.from`	`noreply@mapas.local`	Endereço remetente

Transportes suportados: smtp://, ses://, mailgun://, sendgrid://, mailchimp://.

Web Push (RedeMapas)

Value	Descrição
`mapas.webPush.enabled`	Habilita notificações Web Push
`mapas.webPush.vapidSubject`	Subject do VAPID (`mailto:` ou URL)
`mapas.webPush.vapidPublicKey`	Chave pública VAPID
`mapas.webPush.existingSecret`	Secret do K8s com a chave privada VAPID

Persistence

Quatro PVCs são criados por padrão:

Volume	Tamanho padrão	Descrição
`persistence.assets`	10Gi	Arquivos públicos de assets
`persistence.publicFiles`	50Gi	Arquivos públicos enviados por usuários
`persistence.privateFiles`	10Gi	Arquivos privados de inscrição
`persistence.varFiles`	5Gi	Diretório `var` de runtime

Ingress

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: mapas.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: mapas-tls
      hosts:
        - mapas.example.com

Skaffold (desenvolvimento em cluster)

For iterative development against a local cluster (kind, minikube):

# Modo dev com hot reload
skaffold dev

# Build e deploy para o perfil de produção
skaffold run -p prod

Atualização

helm upgrade mapas ./helm/mapas --reuse-values \
  --set image.tag=<new-version>

As migrações em db-updates.php rodam automaticamente no startup do contêiner via entrypoint.sh. Nenhuma etapa manual de migração é necessária durante a atualização.

Escalabilidade

replicaCount: 3

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

Se você escalar para mais de uma réplica, garanta que os PVCs usem modo de acesso ReadWriteMany ou utilize armazenamento compartilhado externo, como S3 ou NFS, para os volumes de assets e arquivos.

Manual Rede das Artes

Kubernetes com Helm