# Helm baseline

Kubernetes-first deploy via a Helm chart at `charts/voltro-app/`.
Per-env overlay values for dev / staging / prod. Local dev still uses
native pnpm or docker-compose — Helm is for deploy, not the dev loop.

## Layout

```
.
├── charts/
│   └── voltro-app/
│       ├── Chart.yaml
│       ├── values.yaml              # defaults
│       ├── values-dev.yaml          # dev cluster overrides
│       ├── values-staging.yaml      # staging overrides
│       ├── values-prod.yaml         # prod overrides
│       ├── .helmignore
│       └── templates/
│           ├── _helpers.tpl
│           ├── deployment-api.yaml
│           ├── deployment-web.yaml
│           ├── service-api.yaml
│           ├── service-web.yaml
│           ├── ingress.yaml
│           ├── configmap.yaml
│           ├── secret.yaml
│           ├── postgres-statefulset.yaml
│           └── postgres-service.yaml
└── deploy/README.md
```

## Common flows

### Local dev

You don't run Helm for local dev. Either:
- `pnpm dev` (native, fastest) + your own local Postgres, OR
- Add the **compose** baseline back temporarily for full-docker dev:
  `voltro baseline set compose` (you can then add helm back; baselines
  aren't mutually exclusive at the file level, only one is "active"
  for tracking purposes).

### Cluster dev (kind / minikube / k3d)

```sh
kind create cluster --name {{projectName}}-dev
pnpm helm:lint
pnpm helm:install:dev
kubectl -n {{projectName}}-dev get pods
kubectl -n {{projectName}}-dev port-forward svc/{{projectName}}-web 5173:5173
```

### Staging / prod deploy

```sh
# Set kubeconfig to your prod cluster first
pnpm helm:install:prod
```

GitOps-style (recommended): commit the chart + values, let ArgoCD or
Flux watch the repo and sync changes. The `pnpm helm:install:*` scripts
are CLI escape hatches, not the primary deploy path.

## Secrets

`templates/secret.yaml` ships an EXAMPLE secret with `change-me`
placeholders. **Never commit real secrets**. Production options:

- **Sealed Secrets** (Bitnami) — encrypted-in-git
- **External Secrets Operator** — pulls from AWS Secrets Manager / Vault
- **SOPS** + helm-secrets plugin — encrypted YAML

Pick one for your cluster + replace the placeholder secret accordingly.

## Postgres in the chart vs external

`values.yaml` defaults to `postgres.embedded: true` which provisions a
single-replica StatefulSet inside the cluster. Fine for dev, **not fine
for prod** — you want a managed Postgres (RDS / Cloud SQL / Crunchy
Operator). Switch by setting:

```yaml
# values-prod.yaml
postgres:
  embedded: false
  externalUrl: postgres://...   # from a Secret, not literal
```

## Switching baselines

`voltro baseline set compose` → restores docker-compose, keeps the
Helm chart on disk (you may want both: compose for local, helm for
deploy). `voltro baseline set bare` → strips everything containerized.

The "active" baseline is tracked in `.voltro/baseline.json` — it
controls what `voltro baseline status` reports and what `voltro
baseline sync` (future) regenerates.