docs: update demo app deployment guide with worker management and improved steps (#567)

# Updated Deployment Documentation for PgFlow Demo App

This PR updates the deployment documentation with a more comprehensive and structured approach, including:

- Added a new section for setting up vault secrets for worker management
- Improved edge function deployment instructions with environment-specific commands
- Separated Cloudflare webapp deployment from function deployment
- Updated GitHub secrets section with more specific naming conventions
- Added detailed instructions for updating production deployments with selective migrations
- Enhanced troubleshooting section with worker-specific guidance
- Updated preview deployment URLs to match current configuration
- Added step-by-step instructions for both full deployments and individual components
- Improved database reset and migration instructions
- Added proper environment variable handling for different deployment environments

These changes support the new worker management features and provide clearer guidance for both automated and manual deployments.

Author: jumski

apps/demo/DEPLOYMENT.md

@@ -26,65 +26,103 @@ For each project (production and preview):
 cd apps/demo
 
 # Link to project
-supabase link --project-ref <PROJECT_REF>
+pnpm supabase link --project-ref <PROJECT_REF>
 
 # Reset database (applies migrations + seed data)
-supabase db reset --linked
+pnpm supabase db reset
+```
+
+### 3. Setting Up Vault Secrets
 
-# Deploy Edge Functions
-supabase functions deploy --project-ref <PROJECT_REF>
+After database migrations, set up vault secrets for worker management:
+
+```bash
+# From apps/demo, source the appropriate env file
+set -a; source .env.production  # or .env.preview
+set +a
+
+# Set up vault secrets and register worker
+psql "$SUPABASE_DB_URL" \
+  -v service_role_key="$SUPABASE_SERVICE_ROLE_KEY" \
+  -v project_ref="$SUPABASE_PROJECT_REF" <<'EOSQL'
+DELETE FROM vault.secrets WHERE name IN ('supabase_service_role_key', 'supabase_project_id');
+SELECT vault.create_secret(:'service_role_key', 'supabase_service_role_key');
+SELECT vault.create_secret(:'project_ref', 'supabase_project_id');
+SELECT pgflow.track_worker_function('article_flow_worker');
+EOSQL
 ```
 
-### 3. Edge Function Secrets
+### 4. Edge Function Secrets
 
 Set environment variables for Edge Functions:
 
 ```bash
 # Set LLM API key (choose Groq or OpenAI)
-supabase secrets set GROQ_API_KEY=your_groq_key_here
+pnpm supabase secrets set GROQ_API_KEY=your_groq_key_here
 # OR
-supabase secrets set OPENAI_API_KEY=your_openai_key_here
+pnpm supabase secrets set OPENAI_API_KEY=your_openai_key_here
 
 # Verify secrets are set
-supabase secrets list
+pnpm supabase secrets list
 ```
 
 Repeat for both production and preview projects.
 
-### 4. Cloudflare Setup
+### 5. Deploy Edge Functions
+
+```bash
+cd apps/demo
+
+# For production
+set -a; source .env.production; set +a
+SUPABASE_ACCESS_TOKEN="$SUPABASE_ACCESS_TOKEN" pnpm supabase functions deploy article_flow_worker --project-ref "$SUPABASE_PROJECT_REF"
+
+# For preview
+pnpm nx run demo:deploy:preview:functions
+```
+
+### 6. Cloudflare Setup
 
 ```bash
 # Authenticate with Cloudflare
 pnpm wrangler login
 
-# Deploy production (from repo root)
-pnpm nx deploy demo
+# Deploy production webapp (from repo root)
+cd apps/demo
+pnpm wrangler deploy
 
 # Deploy preview
-pnpm nx deploy:preview demo
+pnpm nx run demo:deploy:preview:webapp
 ```
 
-### 5. GitHub Secrets
+### 7. GitHub Secrets
 
 Add these secrets to your GitHub repository (Settings → Secrets):
 
 **Supabase (Production):**
 
-- `SUPABASE_ACCESS_TOKEN` - Personal access token from https://supabase.com/dashboard/account/tokens
-- `PRODUCTION_PROJECT_ID` - Production project ref
-- `PRODUCTION_DB_PASSWORD` - Production database password
+- `DEMO_PRODUCTION_SUPABASE_URL` - Production project URL
+- `DEMO_PRODUCTION_SUPABASE_ANON_KEY` - Production anon key
+- `DEMO_PRODUCTION_SUPABASE_PROJECT_REF` - Production project ref
+- `DEMO_PRODUCTION_SUPABASE_SERVICE_ROLE_KEY` - Production service role key
+- `DEMO_PRODUCTION_SUPABASE_DB_URL` - Production database connection string
+- `DEMO_PRODUCTION_SUPABASE_ACCESS_TOKEN` - Supabase personal access token
 
 **Supabase (Preview):**
 
-- `PREVIEW_PROJECT_ID` - Preview project ref
-- `PREVIEW_DB_PASSWORD` - Preview database password
+- `DEMO_PREVIEW_SUPABASE_URL` - Preview project URL
+- `DEMO_PREVIEW_SUPABASE_ANON_KEY` - Preview anon key
+- `DEMO_PREVIEW_SUPABASE_PROJECT_REF` - Preview project ref
+- `DEMO_PREVIEW_SUPABASE_SERVICE_ROLE_KEY` - Preview service role key
+- `DEMO_PREVIEW_SUPABASE_DB_URL` - Preview database connection string
+- `DEMO_PREVIEW_SUPABASE_ACCESS_TOKEN` - Supabase personal access token
 
 **Cloudflare:**
 
 - `CLOUDFLARE_API_TOKEN` - API token from Cloudflare dashboard
 - `CLOUDFLARE_ACCOUNT_ID` - Account ID from Cloudflare dashboard
 
-### 6. Enable Supabase Branching (Optional)
+### 8. Enable Supabase Branching (Optional)
 
 For automatic per-PR preview databases:
 
@@ -95,53 +133,102 @@ For automatic per-PR preview databases:
 ## Deployment URLs
 
 - **Production**: https://demo.pgflow.dev
-- **Preview**: https://pr-{number}.pgflow-demo.workers.dev
+- **Preview**: https://pr-{number}-pgflow-demo.jumski.workers.dev
 
 ## Manual Deployments
 
 ### Production
 
 ```bash
-pnpm nx deploy demo
+# Full production deployment
+pnpm nx run demo:deploy
+
+# Or step-by-step from apps/demo:
+cd apps/demo
+pnpm wrangler deploy
 ```
 
 ### Preview
 
 ```bash
+# Full preview deployment (db + functions + webapp)
+pnpm nx run demo:deploy:preview
+
 # With custom name (using script directly)
 cd apps/demo
-./scripts/deploy-preview.sh my-feature
-
-# With custom name (using nx)
-PREVIEW_NAME=my-feature pnpm nx deploy:preview demo
+PREVIEW_NAME=my-feature ./scripts/deploy-preview.sh
 
 # With PR number (CI)
-PR_NUMBER=123 pnpm nx deploy:preview demo
+PR_NUMBER=123 pnpm nx run demo:deploy:preview
 
 # Default local preview
-pnpm nx deploy:preview demo
+pnpm nx run demo:deploy:preview
 ```
 
 ### Reset Database
 
 ```bash
 cd apps/demo
-supabase link --project-ref <PROJECT_REF>
-supabase db reset --linked
+pnpm supabase link --project-ref <PROJECT_REF>
+pnpm supabase db reset
+```
+
+## Updating Production Deployments
+
+When updating production with new pgflow migrations, apply them selectively in order:
+
+```bash
+cd apps/demo
+
+# Link to production
+set -a; source .env.production; set +a
+SUPABASE_ACCESS_TOKEN="$SUPABASE_ACCESS_TOKEN" pnpm supabase link --project-ref "$SUPABASE_PROJECT_REF"
+
+# Apply pgflow migrations in order
+pnpm supabase migration up --file 20251226231000_20251104080523_pgflow_upgrade_pgmq_1_5_1.sql
+pnpm supabase migration up --file 20251226232000_20251130000000_pgflow_auto_compilation.sql
+pnpm supabase migration up --file 20251226233000_20251209074533_pgflow_worker_management.sql
+
+# Set up vault secrets (worker_management adds track_worker_function)
+psql "$SUPABASE_DB_URL" \
+  -v service_role_key="$SUPABASE_SERVICE_ROLE_KEY" \
+  -v project_ref="$SUPABASE_PROJECT_REF" <<'EOSQL'
+DELETE FROM vault.secrets WHERE name IN ('supabase_service_role_key', 'supabase_project_id');
+SELECT vault.create_secret(:'service_role_key', 'supabase_service_role_key');
+SELECT vault.create_secret(:'project_ref', 'supabase_project_id');
+SELECT pgflow.track_worker_function('article_flow_worker');
+EOSQL
+
+# Deploy edge functions
+SUPABASE_ACCESS_TOKEN="$SUPABASE_ACCESS_TOKEN" pnpm supabase functions deploy article_flow_worker --project-ref "$SUPABASE_PROJECT_REF"
+
+# Apply remaining migrations
+pnpm supabase migration up --file 20251230202447_20251225163110_pgflow_add_flow_input_column.sql
+
+# Deploy webapp
+pnpm wrangler deploy
 ```
 
 ## Troubleshooting
 
 **Edge Functions failing:**
 
-- Check secrets are set: `supabase secrets list`
+- Check secrets are set: `pnpm supabase secrets list`
 - Verify you're linked to correct project: `cat supabase/.branches/_current_branch`
+- Ensure GROQ_API_KEY or OPENAI_API_KEY is set
 
 **Database out of sync:**
 
-- Run `supabase db reset --linked` to reapply all migrations
+- Run `pnpm supabase db reset` to reapply all migrations
+- For production, use selective migration process above
+
+**Worker not auto-restarting:**
+
+- Verify vault secrets are set: `SELECT * FROM vault.secrets;`
+- Check worker is tracked: `SELECT * FROM pgflow.worker_functions;`
 
 **Cloudflare deployment fails:**
 
 - Ensure you're authenticated: `pnpm wrangler whoami`
 - Check wrangler.toml routes match your domain
+- For production, use `pnpm wrangler deploy` (no --env flag)