Kubernetes (Helm)
Install WonderMoney on a Kubernetes cluster with the Helm chart, with your own Postgres or the bundled one.
The Helm chart runs the same images as the Docker Compose install: the API, its background worker and the web app, with an optional Ingress. Postgres is your own by default; a bundled one is available for small installs. Each release publishes the chart next to its images, with the same version number.
You need a cluster running Kubernetes 1.27 or newer and Helm 3.8 or newer.
Install
With the bundled Postgres:
helm install wondermoney oci://ghcr.io/wondermoney/charts/wondermoney \
--version 1.7.0 \
--namespace wondermoney --create-namespace \
--set postgresql.enabled=trueChart 1.7.0 runs the 1.7.0 images; image.tag picks others. On the first start, the API creates the database and loads the reference data, which takes a minute or two. Without an Ingress, reach it with a port forward:
kubectl -n wondermoney port-forward svc/wondermoney-web 3000:3000 &
kubectl -n wondermoney port-forward svc/wondermoney-api 3001:3001 &Then open http://localhost:3000 and create your account. The first account can always sign up; after that, SIGNUP_MODE decides who else can.
To see every setting:
helm show values oci://ghcr.io/wondermoney/charts/wondermoney --version 1.7.0Your own Postgres
Leave postgresql.enabled off and point the chart at your database in a values file:
database:
host: postgres.example.com
name: wondermoney
user: wondermoney
# A Secret you created, with the password under the key `password`
existingSecret: wondermoney-dbOr give a connection string in database.url (add ?sslmode=require for TLS), or one stored in your Secret with database.existingSecretUrlKey. The chart refuses to install with no database at all.
One hostname
With an Ingress, one hostname serves everything: /v1 and /api/auth go to the API, everything else to the web app. No cookie domain is needed.
ingress:
enabled: true
className: traefik # or nginx, or empty for the cluster's default
host: money.example.com
annotations:
cert-manager.io/cluster-issuer: letsencrypt
tls:
- secretName: wondermoney-tls
hosts: [money.example.com]APP_URL and API_URL follow the Ingress (https://money.example.com here, https because tls is set), and TRUST_PROXY becomes 1 for the ingress controller. Set them in config if your setup differs, for example TRUST_PROXY: "2" with a load balancer in front of the controller that forwards the visitor's address.
Two hostnames
Set ingress.apiHost to give the API its own hostname. Both then need the shared cookie domain, as in the Compose install:
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.comThe chart refuses two hostnames without the cookie domain, because sign-in would not work.
Configure
The config map takes the settings of Configure your instance, by the same names and in the same sections as .env. Credentials go in secrets instead, which the chart stores in a Secret. Anything else goes in extraEnv, which reaches the API and the worker, or in webExtraEnv for the web app.
config:
INSTANCE_NAME: Our money
SIGNUP_MODE: invite
EMAIL_FROM: money@example.com
SMTP_HOST: smtp.example.com
SMTP_USER: money@example.com
secrets:
SMTP_PASSWORD: change-meThe web app gets only the addresses, the NEXT_PUBLIC_ settings and RECAPTCHA_SECRET_KEY, never the database password or the API's secrets. To keep credentials out of values files altogether, put them in a Secret you manage and name it in existingSecret; its keys win over everything else.
The encryption key
The API refuses to start without five secrets: BETTER_AUTH_SECRET, CREDENTIAL_ENCRYPTION_KEY_V1, EMAIL_OPT_OUT_SIGNING_SECRET, ADMIN_API_KEY and INTERNAL_SERVICE_API_KEY. The chart generates them on the first install, together with the bundled Postgres password, in the Secret wondermoney-generated (for a release named wondermoney; the install notes print its name). Every upgrade keeps them, and Helm leaves that Secret in place when you uninstall.
CREDENTIAL_ENCRYPTION_KEY_V1 encrypts every user's stored bank credentials. Without it they are unreadable, and a restored database is useless. Copy it somewhere safe, apart from your database backups:
kubectl -n wondermoney get secret wondermoney-generated \
-o jsonpath='{.data.CREDENTIAL_ENCRYPTION_KEY_V1}' | base64 -d; echoGenerating them needs Helm to read the cluster. Tools that render the chart without a cluster, such as Argo CD, would generate new secrets on every sync. With those, set generatedSecrets.enabled: false and provide all five in existingSecret. Create the key with openssl rand -base64 32 and the others with openssl rand -hex 32.
The worker
The worker runs the background jobs and their schedules (bank and price syncs, imports, scheduled emails), so there is always exactly one. The chart has no replica setting for it and refuses worker.replicas, and an upgrade stops the old worker before starting the new one. The API and the web app scale with api.replicas and web.replicas.
Health
The API's probes use GET /v1/health, the web app's /health and the worker's /health on port 3002. GET /v1/health/ready checks the whole instance, the worker and the job queue included: use it for an uptime monitor (see Monitoring) rather than as a probe, since a late worker would otherwise take the whole app offline. helm test runs the same checks from inside the cluster:
helm test wondermoney -n wondermoney --logsUpgrade
helm upgrade wondermoney oci://ghcr.io/wondermoney/charts/wondermoney \
--version 1.7.0 -n wondermoney --reuse-valuesThe API applies new database migrations when it starts, and the generated secrets stay as they are.
Back up
The Compose install's scheduled backups (the backup profile) are not part of the chart. With your own Postgres, back it up as you back up that server. With the bundled one, take a dump, by hand or from a CronJob of your own:
# Back up
kubectl -n wondermoney exec wondermoney-postgresql-0 -- \
pg_dump -U wondermoney -Fc wondermoney > wondermoney-$(date +%F).dump
# Restore: stop the app, load the dump into a fresh database, start the app again
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 1Keep the encryption key with your backups.
Uninstall
helm uninstall wondermoney -n wondermoneyThis keeps the generated secrets and the bundled Postgres volume, so reinstalling under the same name in the same namespace finds your data and keys. To remove them too:
kubectl -n wondermoney delete secret wondermoney-generated
kubectl -n wondermoney delete pvc data-wondermoney-postgresql-0