From b433a0029c39ff8dd76436412909349e77bc56fc Mon Sep 17 00:00:00 2001
From: sallyom <somalley@redhat.com>
Date: Mon, 12 Jan 2026 13:01:14 -0500
Subject: [PATCH] update deployment docs for minio bucket creation

Signed-off-by: sallyom <somalley@redhat.com>
---
 README.md                      | 25 ++++++++++++++++---
 components/manifests/deploy.sh | 22 +++++++++++++++++
 docs/minio-quickstart.md       | 44 ++++++++++++++++++++++------------
 3 files changed, 73 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 3002a85c5..a92323ffc 100644
--- a/README.md
+++ b/README.md
@@ -124,7 +124,19 @@ That's it! Access the app at `http://$(minikube ip):30030` (get IP with `make lo
 
 ## Quick Start
 
-### 1. Deploy to OpenShift
+### 1. Prepare MinIO Credentials (Required)
+
+Before deploying, create MinIO credentials for S3 storage:
+
+```bash
+cd components/manifests/base
+cp minio-credentials-secret.yaml.example minio-credentials-secret.yaml
+# Edit credentials (change admin/changeme123 for production)
+vi minio-credentials-secret.yaml
+cd ../..
+```
+
+### 2. Deploy to OpenShift
 
 Deploy using the default images from `quay.io/ambient_code`:
 
@@ -134,13 +146,20 @@ cp components/manifests/env.example components/manifests/.env
 # Edit .env and set at least ANTHROPIC_API_KEY
 
 # Deploy to ambient-code namespace (default)
+# This automatically sets up MinIO and creates the session storage bucket
 make deploy
 
 # Or deploy to custom namespace
 make deploy NAMESPACE=my-namespace
 ```
 
-### 2. Verify Deployment
+**What happens during deployment:**
+- MinIO is deployed with your credentials
+- The `ambient-sessions` bucket is automatically created
+- Versioning and privacy policies are configured
+- All components wait for dependencies to be ready
+
+### 3. Verify Deployment
 
 ```bash
 # Check pod status
@@ -150,7 +169,7 @@ oc get pods -n ambient-code
 oc get services,routes -n ambient-code
 ```
 
-### 3. Access the Web Interface
+### 4. Access the Web Interface
 
 ```bash
 # Get the route URL
diff --git a/components/manifests/deploy.sh b/components/manifests/deploy.sh
index c3f33eb3a..4413258ac 100755
--- a/components/manifests/deploy.sh
+++ b/components/manifests/deploy.sh
@@ -367,6 +367,28 @@ oc rollout status deployment/backend-api --namespace=${NAMESPACE} --timeout=300s
 oc rollout status deployment/agentic-operator --namespace=${NAMESPACE} --timeout=300s
 oc rollout status deployment/frontend --namespace=${NAMESPACE} --timeout=300s
 
+# Wait for MinIO and setup bucket
+echo -e "${YELLOW}Waiting for MinIO to be ready...${NC}"
+oc rollout status deployment/minio --namespace=${NAMESPACE} --timeout=300s || {
+    echo -e "${YELLOW}⚠️  MinIO deployment not found or failed to start${NC}"
+    echo -e "${YELLOW}Sessions will fail without S3 storage. Deploy MinIO separately if needed.${NC}"
+}
+
+# Setup MinIO bucket automatically
+echo -e "${YELLOW}Setting up MinIO bucket...${NC}"
+if [ -f "../../scripts/setup-minio.sh" ]; then
+    # Run setup script (it handles existing bucket gracefully)
+    NAMESPACE=${NAMESPACE} ../../scripts/setup-minio.sh || {
+        echo -e "${YELLOW}⚠️  MinIO setup encountered an issue (may be already configured)${NC}"
+        echo -e "${YELLOW}If sessions fail with 'init-hydrate' errors, run manually:${NC}"
+        echo -e "   ${BLUE}make setup-minio NAMESPACE=${NAMESPACE}${NC}"
+    }
+else
+    echo -e "${YELLOW}⚠️  MinIO setup script not found at ../../scripts/setup-minio.sh${NC}"
+    echo -e "${YELLOW}Run manually after deployment:${NC}"
+    echo -e "   ${BLUE}make setup-minio NAMESPACE=${NAMESPACE}${NC}"
+fi
+
 # Get service and route information
 echo -e "${BLUE}Getting service and route information...${NC}"
 echo ""
diff --git a/docs/minio-quickstart.md b/docs/minio-quickstart.md
index 26fbe2a5c..d214afa3f 100644
--- a/docs/minio-quickstart.md
+++ b/docs/minio-quickstart.md
@@ -6,7 +6,7 @@ MinIO provides in-cluster S3-compatible storage for Ambient Code session state,
 
 ## Quick Setup
 
-### 1. Deploy MinIO
+### 1. Prepare MinIO Credentials (Before Deployment)
 
 ```bash
 # Create MinIO credentials secret
@@ -15,26 +15,26 @@ cp minio-credentials-secret.yaml.example minio-credentials-secret.yaml
 
 # Edit credentials (change admin/changeme123 to secure values)
 vi minio-credentials-secret.yaml
-
-# Apply the secret
-kubectl apply -f minio-credentials-secret.yaml -n ambient-code
-
-# MinIO deployment is included in base manifests, so deploy normally
-make deploy NAMESPACE=ambient-code
 ```
 
-### 2. Create Bucket
+**Important:** Create this secret BEFORE running deploy.sh so MinIO has credentials on startup.
 
-```bash
-# Run automated setup
-make setup-minio NAMESPACE=ambient-code
+### 2. Deploy (Bucket Created Automatically)
 
-# Or manually:
-kubectl port-forward svc/minio 9001:9001 -n ambient-code &
-open http://localhost:9001
-# Login with credentials, create bucket "ambient-sessions"
+```bash
+# MinIO deployment AND bucket setup are both automated
+cd components/manifests
+./deploy.sh
 ```
 
+The deploy.sh script will:
+- Deploy MinIO with your credentials
+- Wait for MinIO to be ready
+- **Automatically create the `ambient-sessions` bucket**
+- Enable versioning and set privacy policy
+
+**No manual bucket creation needed!** 🎉
+
 ### 3. Configure Project
 
 Navigate to project settings in the UI and configure:
@@ -50,6 +50,20 @@ Navigate to project settings in the UI and configure:
 
 Click **Save Integration Secrets**.
 
+### 4. Troubleshooting: Manual Bucket Setup (If Needed)
+
+If the automatic setup failed or you need to re-create the bucket:
+
+```bash
+# Run manual setup
+make setup-minio NAMESPACE=ambient-code
+
+# Or directly:
+./scripts/setup-minio.sh
+```
+
+This is safe to run multiple times - it skips bucket creation if it already exists.
+
 ## Accessing MinIO Console
 
 ### Option 1: Port Forward