feat : update

k8s.md

@@ -1,83 +1,100 @@
-# Updating `.env` in Kubernetes
+# Push `.env` to Kubernetes
 
-Buzz Sheet uses the `buzz-sheet-env` Secret in the `buzz-sheet` namespace. The
-local `.env` file is ignored by Git and must never be committed.
+Buzz Sheet reads private configuration from the `buzz-sheet-env` Kubernetes
+Secret in the `buzz-sheet` namespace. Use the local `.env` file as the source.
+Never commit `.env` or paste its values into a Kubernetes manifest.
 
-This repository uses hand-authored Kustomize manifests rather than a
-Kuber-managed Compose file, so synchronize `.env` with `kubectl`.
+This repository uses the manifests under `k8s/`, not a Kuber `compose.yml`, so
+environment-only updates are applied with `kubectl`.
 
-## Push an updated `.env`
+## 1. Check the target cluster
 
-From the repository root, confirm that `kubectl` is connected to the intended
-cluster:
+Run these commands from the repository root:
 
 ```bash
-cd /home/gunshiz/buzz-sheet
 kubectl config current-context
 kubectl get namespace buzz-sheet
 ```
 
-Create or update the Secret without printing its values:
+Stop if the context is not the cluster you intend to update.
+
+Confirm that `.env` exists, then inspect only its variable names:
+
+```bash
+test -f .env
+awk -F= '/^[A-Za-z_][A-Za-z0-9_]*=/{print $1}' .env
+```
+
+## 2. Create or update the Secret
+
+The following command builds the Secret locally and sends it directly to the
+cluster. It does not create a plaintext YAML file:
 
 ```bash
 kubectl create secret generic buzz-sheet-env \
   --namespace buzz-sheet \
   --from-env-file=.env \
   --dry-run=client \
-  --output=yaml | kubectl apply --filename=-
+  --output=yaml \
+  | kubectl apply --filename=-
 ```
 
-Running pods do not reload Secret values automatically. Restart the web
-application and both workers, then wait for each rollout:
+Verify that the Secret exists without displaying its values:
+
+```bash
+kubectl get secret buzz-sheet-env \
+  --namespace buzz-sheet \
+  --output='go-template={{range $key, $value := .data}}{{$key}}{{"\n"}}{{end}}'
+```
+
+## 3. Restart the application
+
+Environment variables sourced from a Secret are read when a pod starts.
+Restart all Buzz Sheet workloads after updating the Secret:
 
 ```bash
 kubectl rollout restart deployment/buzz-sheet \
   --namespace buzz-sheet
-
 kubectl rollout restart deployment/buzz-sheet-worker \
   --namespace buzz-sheet
-
 kubectl rollout restart deployment/buzz-sheet-discord-worker \
   --namespace buzz-sheet
+```
 
+Wait for every rollout to finish:
+
+```bash
 kubectl rollout status deployment/buzz-sheet \
   --namespace buzz-sheet \
   --timeout=10m
-
 kubectl rollout status deployment/buzz-sheet-worker \
   --namespace buzz-sheet \
   --timeout=10m
-
 kubectl rollout status deployment/buzz-sheet-discord-worker \
   --namespace buzz-sheet \
   --timeout=10m
 ```
 
-Verify PostgreSQL and Redis readiness, then inspect the application logs:
+## 4. Verify the deployment
 
 ```bash
 curl -fsS 'https://guide.sudloh.com/api/health?ready=1'
 bun logs
 ```
 
-The health response should report `"status":"ready"`, with both `database`
-and `redis` set to `"ok"`.
+The health response should show `"status":"ready"` with both `database` and
+`redis` set to `"ok"`.
 
-## Important exceptions
+## Troubleshooting
 
-- Updating the Secret does not apply database migrations or seed data. If
-  `DATABASE_URL` now points to a new database, migrate and seed that database
-  before restarting the application.
-- Better Auth errors about missing database fields require a schema migration.
-  Pushing `.env` again will not fix them.
-- `NEXT_DEPLOYMENT_ID` is controlled by `buzz-sheet-config` and the immutable
-  image revision. Do not change it for an environment-only update.
-- `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` is embedded during `next build`. Rotating
-  it requires building and deploying a new image; restarting the existing image
-  is not sufficient.
-- If `BETTER_AUTH_URL` or the public hostname changes, update the Kubernetes
-  ingress and Cloudflare/DNS configuration as well.
-- `S3_ENDPOINT` is the private Garage API used for writes. `S3_PUBLIC_URL`
-  is the public read-only CDN base (production uses
-  `https://buzz-cdn.astrxl.dev`). Browser uploads go through the authenticated
-  application route; do not point `S3_ENDPOINT` at the CDN hostname.
+- `namespace "buzz-sheet" not found`: apply the base manifests first with
+  `kubectl apply --kustomize k8s/base`.
+- Pods fail after the restart: inspect them with
+  `kubectl describe pod --namespace buzz-sheet <pod-name>` and `bun logs`.
+- A new `DATABASE_URL` points to an empty database: run the database migrations
+  before serving traffic. Updating the Secret does not migrate the database.
+- `NEXT_DEPLOYMENT_ID` comes from `buzz-sheet-config`, not `.env`.
+- Rotating `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` requires a new application
+  build and deployment because Next.js uses it during the build.
+- `S3_ENDPOINT` must be the private S3-compatible API endpoint.
+  `S3_PUBLIC_URL` must be the public read URL.