From c0546814aabcb6dace202b2b3a613a69eb211e58 Mon Sep 17 00:00:00 2001
From: Graham McIntire <graham@mcintire.me>
Date: Fri, 6 Mar 2026 13:21:21 -0600
Subject: [PATCH] docs: add deployment instructions for staging and production

---
 CLAUDE.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 0cc20e6e..453d7f6c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -242,6 +242,112 @@ kubectl rollout restart deployment/towerops -n towerops
 
 **Deployment**: FluxCD auto-applies `k8s/` manifests. Manual: `kubectl apply -k k8s/`
 
+## Deployment
+
+### Branch-Based Deployment Strategy
+
+Towerops uses branch-based deployment with Forgejo CI/CD:
+
+**Staging (Dokku):**
+- Push to `main` branch triggers automatic deploy to Dokku staging server
+- Direct git push to Dokku (no Docker build)
+- Buildpack-based deployment (detects Elixir/Phoenix)
+- URL: staging.towerops.app (or configured Dokku domain)
+
+**Production (Kubernetes):**
+- Push to `production` branch triggers Docker build + k8s deployment
+- Builds Docker image from `k8s/Dockerfile`
+- Pushes to container registry
+- Updates `k8s/deployment.yaml` with new image tag
+- FluxCD detects change and applies to cluster
+
+### Deploying Changes
+
+**To staging:**
+```bash
+git push origin main
+# CI automatically deploys to Dokku
+# Watch: https://git.mcintire.me/graham/towerops-web/actions
+```
+
+**To production:**
+```bash
+# Merge main → production
+git checkout production
+git merge main
+git push origin production
+
+# Or fast-forward if no conflicts
+git push origin main:production
+
+# CI builds Docker image and updates k8s manifests
+# FluxCD applies within ~5 minutes
+```
+
+**Direct Dokku deploy (bypass CI):**
+```bash
+# Add Dokku remote (one-time)
+git remote add dokku dokku@204.110.191.231:towerops
+
+# Force push to deploy
+git push dokku main:main --force
+```
+
+**Manual production deploy:**
+```bash
+# Apply k8s manifests directly
+kubectl apply -k k8s/
+
+# Or trigger rollout restart
+kubectl rollout restart deployment/towerops -n towerops
+```
+
+### Deployment Verification
+
+**Staging:**
+```bash
+# Check Dokku logs
+ssh dokku@204.110.191.231 logs towerops --tail 100
+
+# Check app status
+ssh dokku@204.110.191.231 ps:report towerops
+```
+
+**Production:**
+```bash
+# Check pod status
+kubectl get pods -n towerops
+
+# Check logs
+kubectl logs -n towerops -l app=towerops --tail=100 -f
+
+# Check deployment status
+kubectl rollout status deployment/towerops -n towerops
+```
+
+### Rollback
+
+**Staging (Dokku):**
+```bash
+# Revert git commit, push to main
+git revert <bad-commit>
+git push origin main
+
+# Or rebuild previous release
+ssh dokku@204.110.191.231 ps:rebuild towerops <release-id>
+```
+
+**Production (Kubernetes):**
+```bash
+# Rollback deployment
+kubectl rollout undo deployment/towerops -n towerops
+
+# Or revert git commit on production branch
+git checkout production
+git revert <bad-commit>
+git push origin production
+```
+
 ## Common Patterns
 
 ### Pagination in LiveView