Quickstart

This page gets Kuben running inside a cluster and signs you in. Publishing apps on your own domain with HTTPS needs a Gateway and cert-manager; that is covered in Production install.

Before you start

• A Kubernetes cluster, 1.29 or later: k3s, kind, EKS, GKE or AKS all work.
• A StorageClass that supports ReadWriteOnce. Kuben keeps users, sessions, releases and the audit log on a 1 GiB volume when it runs on SQLite (the default).
• Helm 3.8 or later (for OCI charts).

No cluster yet?

On a single server, k3s installs in under a minute and ships a StorageClass, a metrics-server and Traefik. See Install the binary for the k3s route.

Install

1. Install the chart. It creates the namespace, the CRDs, RBAC, a persistent volume and one Kuben pod.

   helm install kuben oci://ghcr.io/teamtem-dev/charts/kuben \
     --namespace kuben-system --create-namespace

2. Wait for the pod to become ready. A pod reports ready only after it has listed every Project, Environment, App and Pod once, so it never answers 404 for objects that exist.

   kubectl -n kuben-system rollout status deploy/kuben

3. Read the generated admin password. It is stored in a Secret and never written to the log.

   kubectl -n kuben-system get secret kuben-initial-admin \
     -o jsonpath='{.data.password}' | base64 -d; echo

4. Open the console through a port-forward.

   kubectl -n kuben-system port-forward svc/kuben 8080:80

   Browse to http://localhost:8080 and sign in as admin@kuben.local with that password. Browsers treat localhost as a secure context, so the Secure session cookie works without TLS.

5. Change the password under Account, then delete the bootstrap Secret:

   kubectl -n kuben-system delete secret kuben-initial-admin

What you have now

• A Kuben deployment in kuben-system running as a non-root user with a read-only root filesystem.
• The kuben.dev custom resources installed: KubenConfig, Project, Environment, App, Release, BuildRun.
• A KubenConfig singleton with empty platform settings. Apps get cluster-internal Services until you set a baseDomain and a Gateway.

Next steps

Deploy something

Follow Deploy your first app: a project, an environment and a running container in a couple of minutes.

Go to production

Production install covers the public URL, custom domains and automatic HTTPS, PostgreSQL and several replicas, backups and upgrades.

Invite the team

Teams and roles explains the four roles, invitations and what an API token may do.

Uninstall

helm uninstall kuben -n kuben-system

The persistent volume carries helm.sh/resource-policy: keep and survives helm uninstall, so a re-install finds its data again. Delete the PVC and the namespace yourself when you really want everything gone. Tenant namespaces created for environments are owned by their Environment resources and are garbage-collected when those are deleted.