Skip to content

Your First App

This guide takes you from zero to a running app in under 5 minutes.

Prerequisites

Before you start, make sure you have:

  • Python 3.11+ installed
  • kubectl installed
  • A working Kubeconfig (e.g., from kind, minikube, k3d, or a remote cluster)
  • Cluster access configuration in your environment (KUBECONFIG env var or ~/.kube/config)

1. Create a Spec

Create a file called deploy.yaml:

apiVersion: helm-me/v1alpha1
kind: Application
metadata:
  name: hello-app

components:
  backend:
    type: web
    image: traefik/whoami:latest
    port: 80

That's it. No templates, no values files, no Chart.yaml.

2. Validate

helm-me lint deploy.yaml

lint output

3. Preview the Manifests

helm-me render deploy.yaml

render prints the full Kubernetes YAML that helm-me would apply — Deployments, Services, Secrets, PVCs, Ingress — so you can inspect before deploying.

render output

4. Deploy

helm-me deploy deploy.yaml --namespace demo --yes
Expected output 
Starting deployment: hello-app
✓ Validated spec
✓ Rendered manifests
✓ Target namespace 'demo' is ready
✓ Applied Deployment/hello-app-backend
✓ Applied Service/hello-app-backend
✓ Saved deployment record
✓ Rollout complete: 1/1 replicas ready
✨ App deployed successfully!

What happens:

  1. Manifests are rendered from the spec
  2. The namespace is created if needed
  3. Resources are applied to the cluster
  4. The deployment is saved to the local registry (~/.helm-me/deployments/)

5. Check Status

helm-me ops pods hello-app
helm-me ops status hello-app
Expected output 
NAME                                READY   STATUS    RESTARTS   AGE 
hello-app-backend-b89c67cf7-6k8q2   1/1     Running   0          45s

6. Stream Logs

helm-me ops logs backend hello-app --tail 50
helm-me ops logs backend hello-app -f  # follow mode

7. Set as Active App

Instead of passing the app name every time:

helm-me app use hello-app

# Now these work without specifying the app:
helm-me ops pods
helm-me ops logs backend
helm-me ops status

Troubleshooting First Deploy

  • No Kubernetes clusters found: Make sure your KUBECONFIG environment variable is set or ~/.kube/config exists.
  • Forbidden: User cannot list resource...: Your active kube context doesn't have privileges to create namespaces or manage resources in the target namespace.
  • Pods are stuck in ErrImagePull / ImagePullBackOff: If you are using a local dev cluster like kind or minikube with a local image, make sure to load the image into the cluster first (e.g. kind load docker-image myapp:latest) and potentially use PullPolicy.NEVER or PullPolicy.IF_NOT_PRESENT.

Next Steps