Deploying Hudu with Helm

Hudu's official Helm Chart lets you install and run self-hosted Hudu on Kubernetes. This article walks through the full lifecycle: getting the chart set up, verifying a healthy install, finding logs when something goes wrong, and keeping your deployment up to date. For the complete option reference (every value the chart accepts), see the chart's README. This article is the narrative, step-by-step version.

Setup and deployment

Before you start

You'll need:

Everything else, database, cache, and app secrets, has a working default or is generated for you on first install.

Adding the chart

The chart is published as an OCI artifact on a public ECR registry, so there's no helm repo add step. You can also browse it on Artifact Hub to see available versions and the full README without pulling anything first.

helm show chart oci://public.ecr.aws/q4n0g0t7/hudu-helm-chart

confirms you can reach the registry and shows the latest published chart version. To download the chart itself, for example to inspect its templates and default values locally, or to install from a local copy:

helm pull oci://public.ecr.aws/q4n0g0t7/hudu-helm-chart --untar

This creates a hudu/ directory with the chart's templates and values.yaml. Add --version <version> to either command to target a specific release instead of the latest one. Neither command needs a login. ECR Public allows anonymous reads.

A minimal install

This relies on the chart's defaults: a bundled single-replica Postgres and Redis, and local-disk file storage on a ReadWriteMany PVC.

helm install my-hudu oci://public.ecr.aws/q4n0g0t7/hudu-helm-chart \
  --set config.domain=hudu.example.com \
  --set ingress.host=hudu.example.com

The four app secrets, secrets.secretKeyBase, secrets.passwordKey, secrets.twoFactorKey, and the bundled Postgres password, are generated for you automatically the first time you install, if you don't set them yourself. See "Handling secrets" further down. It matters once you get to upgrades.

If you'd rather set them explicitly up front:

helm install my-hudu oci://public.ecr.aws/q4n0g0t7/hudu-helm-chart \
  --set config.domain=hudu.example.com \
  --set ingress.host=hudu.example.com \
  --set secrets.secretKeyBase=$(openssl rand -hex 64) \
  --set secrets.passwordKey=$(openssl rand -hex 16) \
  --set secrets.twoFactorKey=$(openssl rand -hex 16) \
  --set postgresql.auth.password=$(openssl rand -hex 16)

A note on TLS

Hudu runs with HTTPS enforcement on, so plain HTTP traffic gets redirected to HTTPS. In practice this means:

• If you're terminating TLS at your Ingress or load balancer (the supported setup), set ingress.tls.enabled: true with cert-manager configured, or bring your own TLS secret. Leave config.behindTlsProxy at its default of true.
• Only set config.behindTlsProxy: false and config.disableSsl: true if there is genuinely no TLS anywhere in front of the pod, for example a throwaway evaluation cluster reached only through kubectl port-forward.

If you're on EKS behind the AWS Load Balancer Controller rather than nginx, you'll also need:

  --set ingress.className=alb \
  --set ingress.annotations."alb\.ingress\.kubernetes\.io/scheme"=internet-facing \
  --set ingress.annotations."alb\.ingress\.kubernetes\.io/target-type"=ip

Choosing file storage

Full option tables for all of the above, including advanced settings like autoscaling, high availability, and resource limits, are in the chart's README.

Running your install

Verify the install

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

You should see a web pod and a worker pod reach Running, plus postgres and redis pods if you're using the bundled versions. A one-off migration Job also runs during install or upgrade and should reach Completed.

kubectl rollout status deployment/my-hudu-hudu-web

waits until the web Deployment has finished rolling out. Useful right after an install or upgrade, or in a CI/CD pipeline.

Access the app

Once the Ingress has picked up an address (kubectl get ingress), Hudu is reachable at the hostname you set in ingress.host, over HTTPS. If you haven't wired up DNS yet and just want to confirm the app itself is healthy, port-forward directly to the service:

kubectl port-forward svc/my-hudu-hudu-web 3000:3000

then visit http://localhost:3000. Note this bypasses your Ingress and TLS entirely, so it's for a quick health check only, not a substitute for the real access path.

Everyday commands

helm status my-hudu

helm get values my-hudu

kubectl logs -l app.kubernetes.io/component=web -f

kubectl logs -l app.kubernetes.io/component=worker -f

kubectl exec -it deploy/my-hudu-hudu-web -- sh

kubectl get all -l app.kubernetes.io/instance=my-hudu

Maintaining your install

Upgrading

helm upgrade my-hudu oci://public.ecr.aws/q4n0g0t7/hudu-helm-chart \
  --version <new-chart-version> \
  --reuse-values

--reuse-values carries forward whatever you've already set, so you only need to pass values you're actively changing. Check the chart's release notes for the version you're moving to. Some upgrades introduce a new default that's worth a deliberate decision rather than inheriting silently, for example a memory limit being added to the web pod where none existed before, or config.behindTlsProxy changing default. The chart's README calls these out explicitly under each affected setting.

The migration Job runs automatically as part of helm upgrade, before the new web and worker pods roll out.

Rolling back

helm rollback my-hudu

rolls back to the previous release revision. This rolls back chart values and the application version, but it does not reverse a completed database migration. A schema change from the release you're rolling back from can remain in place.

Handling secrets

The app's core secrets, the secret key base, the password encryption key, the 2FA key, and the bundled Postgres password, are generated once on first install and stored in a real Kubernetes Secret (<release>-hudu-generated). They are not regenerated on later upgrades.

Back this Secret up:

kubectl get secret my-hudu-hudu-generated -o yaml  my-hudu-generated-backup.yaml

and store it somewhere as securely as you'd store the encrypted data it protects. It effectively is the key to that data.

Backup considerations

• Database: if you're using the bundled Postgres, back up its PVC on whatever schedule your cluster's storage supports (volume snapshots), or point the chart at an externally-managed, already-backed-up Postgres instance instead (externalDatabase.*). Recommended for anything beyond evaluation.
• File storage: back up the uploads PVC, or rely on your S3 bucket's own versioning and replication if you're using S3 storage.
• The generated-secrets Secret: back it up once and keep it somewhere safe. It's not reproducible from anything else.

Changing configuration

Ordinary config changes, resource limits, ingress annotations, feature flags under config.*, are a normal helm upgrade --reuse-values --set <key>=<value>, or by maintaining your own values file and passing -f values.yaml.

FAQ

Troubleshooting

Start with pod status, then drill into the specific pod that isn't healthy:

kubectl get pods -l app.kubernetes.io/instance=my-hudu -o wide
kubectl describe pod <pod-name>
kubectl logs <pod-name>
kubectl logs <pod-name> --previous   # if the pod already restarted

kubectl logs job/my-hudu-hudu-migrate

If you're stuck on something not covered here, contact Hudu support with:

• The chart and app version you're running (helm get values my-hudu, helm list).
• The output of kubectl describe pod for the affected pod.
• Recent logs from the affected pod(s).

That's usually enough for us to help diagnose the issue quickly.