Kubernetes (Helm)
Instala o WonderMoney num cluster Kubernetes com o chart Helm, com o teu próprio Postgres ou com o incluído.
O chart Helm usa as mesmas imagens que a instalação com Docker Compose: a API, o seu worker de tarefas em segundo plano e a aplicação web, com um Ingress opcional. Por omissão, o Postgres é o teu; há um incluído para instalações pequenas. Cada versão publica o chart ao lado das suas imagens, com o mesmo número de versão.
Precisas de um cluster com Kubernetes 1.27 ou mais recente e do Helm 3.8 ou mais recente.
Instalar
Com o Postgres incluído:
helm install wondermoney oci://ghcr.io/wondermoney/charts/wondermoney \
--version 1.7.0 \
--namespace wondermoney --create-namespace \
--set postgresql.enabled=trueO chart 1.7.0 usa as imagens 1.7.0; image.tag escolhe outras. No primeiro arranque, a API cria a base de dados e carrega os dados de referência, o que demora um ou dois minutos. Sem Ingress, chega-lhe com um port forward:
kubectl -n wondermoney port-forward svc/wondermoney-web 3000:3000 &
kubectl -n wondermoney port-forward svc/wondermoney-api 3001:3001 &Depois abre http://localhost:3000 e cria a tua conta. A primeira conta pode sempre registar-se; a partir daí, SIGNUP_MODE decide quem mais pode.
Para ver todas as definições:
helm show values oci://ghcr.io/wondermoney/charts/wondermoney --version 1.7.0O teu próprio Postgres
Deixa postgresql.enabled desligado e indica a tua base de dados num ficheiro de valores:
database:
host: postgres.example.com
name: wondermoney
user: wondermoney
# Um Secret criado por ti, com a palavra-passe na chave `password`
existingSecret: wondermoney-dbOu dá uma connection string em database.url (acrescenta ?sslmode=require para TLS), ou uma guardada no teu Secret com database.existingSecretUrlKey. O chart recusa instalar sem nenhuma base de dados.
Um só nome de anfitrião
Com um Ingress, um só nome de anfitrião serve tudo: /v1 e /api/auth vão para a API, tudo o resto para a aplicação web. Não é preciso domínio de cookie.
ingress:
enabled: true
className: traefik # ou nginx, ou vazio para o do cluster
host: money.example.com
annotations:
cert-manager.io/cluster-issuer: letsencrypt
tls:
- secretName: wondermoney-tls
hosts: [money.example.com]APP_URL e API_URL seguem o Ingress (aqui https://money.example.com, em https porque tls está definido), e TRUST_PROXY passa a 1 por causa do ingress controller. Define-os em config se a tua configuração for diferente, por exemplo TRUST_PROXY: "2" com um balanceador de carga à frente do controller que reencaminha o endereço do visitante.
Dois nomes de anfitrião
Define ingress.apiHost para dar à API o seu próprio nome de anfitrião. Ambos precisam então do domínio de cookie partilhado, como na instalação com Compose:
ingress:
enabled: true
host: money.example.com
apiHost: api.money.example.com
tls:
- secretName: wondermoney-tls
hosts: [money.example.com, api.money.example.com]
config:
AUTH_COOKIE_DOMAIN: .example.com
NEXT_PUBLIC_AUTH_COOKIE_DOMAIN: .example.comO chart recusa dois nomes de anfitrião sem o domínio de cookie, porque o início de sessão não funcionaria.
Configurar
O mapa config aceita as definições de Configurar a tua instância, com os mesmos nomes e nas mesmas secções que o .env. As credenciais vão antes em secrets, que o chart guarda num Secret. Tudo o resto vai em extraEnv, que chega à API e ao worker, ou em webExtraEnv para a aplicação web.
config:
INSTANCE_NAME: O nosso dinheiro
SIGNUP_MODE: invite
EMAIL_FROM: money@example.com
SMTP_HOST: smtp.example.com
SMTP_USER: money@example.com
secrets:
SMTP_PASSWORD: change-meA aplicação web recebe só os endereços, as definições NEXT_PUBLIC_ e RECAPTCHA_SECRET_KEY, nunca a palavra-passe da base de dados nem os segredos da API. Para deixar as credenciais fora dos ficheiros de valores, põe-nas num Secret gerido por ti e indica-o em existingSecret; as suas chaves prevalecem sobre tudo o resto.
A chave de encriptação
A API recusa arrancar sem cinco segredos: BETTER_AUTH_SECRET, CREDENTIAL_ENCRYPTION_KEY_V1, EMAIL_OPT_OUT_SIGNING_SECRET, ADMIN_API_KEY e INTERNAL_SERVICE_API_KEY. O chart gera-os na primeira instalação, juntamente com a palavra-passe do Postgres incluído, no Secret wondermoney-generated (para uma release chamada wondermoney; as notas da instalação mostram o nome). Cada atualização mantém-nos, e o Helm deixa esse Secret no lugar quando desinstalas.
CREDENTIAL_ENCRYPTION_KEY_V1 encripta as credenciais bancárias guardadas de cada utilizador. Sem ela ficam ilegíveis, e uma base de dados restaurada não serve de nada. Copia-a para um lugar seguro, à parte das cópias de segurança da base de dados:
kubectl -n wondermoney get secret wondermoney-generated \
-o jsonpath='{.data.CREDENTIAL_ENCRYPTION_KEY_V1}' | base64 -d; echoGerá-los exige que o Helm leia o cluster. Ferramentas que geram o chart sem cluster, como o Argo CD, gerariam segredos novos a cada sincronização. Com essas, define generatedSecrets.enabled: false e fornece os cinco em existingSecret. Cria a chave com openssl rand -base64 32 e os outros com openssl rand -hex 32.
O worker
O worker corre as tarefas em segundo plano e os seus agendamentos (sincronizações de bancos e preços, importações, emails agendados), por isso há sempre exatamente um. O chart não tem definição de réplicas para ele e recusa worker.replicas, e uma atualização para o worker antigo antes de iniciar o novo. A API e a aplicação web escalam com api.replicas e web.replicas.
Saúde
As sondas da API usam GET /v1/health, as da aplicação web /health e as do worker /health na porta 3002. GET /v1/health/ready verifica a instância inteira, incluindo o worker e a fila de tarefas: usa-o num monitor de disponibilidade (consulta Monitorização) e não como sonda, porque um worker atrasado tiraria a aplicação toda do ar. helm test faz as mesmas verificações de dentro do cluster:
helm test wondermoney -n wondermoney --logsAtualizar
helm upgrade wondermoney oci://ghcr.io/wondermoney/charts/wondermoney \
--version 1.7.0 -n wondermoney --reuse-valuesA API aplica as novas migrações da base de dados quando arranca, e os segredos gerados ficam como estão.
Cópia de segurança
As cópias de segurança agendadas da instalação com Compose (o perfil backup) não fazem parte do chart. Com o teu próprio Postgres, faz a cópia como fazes nesse servidor. Com o incluído, faz um dump, à mão ou a partir de um CronJob teu:
# Cópia de segurança
kubectl -n wondermoney exec wondermoney-postgresql-0 -- \
pg_dump -U wondermoney -Fc wondermoney > wondermoney-$(date +%F).dump
# Restaurar: para a aplicação, carrega a cópia numa base de dados nova, volta a iniciar a aplicação
kubectl -n wondermoney scale deploy wondermoney-api wondermoney-worker wondermoney-web --replicas 0
kubectl -n wondermoney exec wondermoney-postgresql-0 -- dropdb -U wondermoney wondermoney
kubectl -n wondermoney exec wondermoney-postgresql-0 -- createdb -U wondermoney wondermoney
kubectl -n wondermoney exec -i wondermoney-postgresql-0 -- \
pg_restore -U wondermoney -d wondermoney < wondermoney-2026-10-04.dump
kubectl -n wondermoney scale deploy wondermoney-api wondermoney-worker wondermoney-web --replicas 1Guarda a chave de encriptação com as tuas cópias de segurança.
Desinstalar
helm uninstall wondermoney -n wondermoneyIsto mantém os segredos gerados e o volume do Postgres incluído, por isso reinstalar com o mesmo nome no mesmo namespace encontra os teus dados e chaves. Para os remover também:
kubectl -n wondermoney delete secret wondermoney-generated
kubectl -n wondermoney delete pvc data-wondermoney-postgresql-0