diff --git a/docs/KOHA_PRODUCTION_DEPLOYMENT.md b/docs/KOHA_PRODUCTION_DEPLOYMENT.md new file mode 100644 index 00000000..d4e63abd --- /dev/null +++ b/docs/KOHA_PRODUCTION_DEPLOYMENT.md @@ -0,0 +1,540 @@ +# Koha Production Deployment Guide +## Deploy Without Live Stripe Integration + +**Date:** 2025-10-08 +**Status:** Pre-Stripe Deployment +**Goal:** Deploy all Koha infrastructure to production, but keep user-facing UI disabled until Stripe is configured + +--- + +## Overview + +This guide walks through deploying the Koha donation system to production in a "staging" mode - all code deployed, database initialized, but public access disabled until Stripe keys are configured. + +**Why Deploy Now:** +- Test production infrastructure before Stripe integration +- Verify database setup and migrations +- Ensure backend API works in production environment +- Frontend code ready for immediate activation when Stripe is configured + +**What's NOT Active:** +- Public navigation links to Koha pages +- Stripe payment processing +- Live donation functionality + +--- + +## Phase 1: Database Initialization + +### 1.1 SSH into Production Server + +```bash +ssh -i /home/theflow/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net +``` + +### 1.2 Navigate to Project Directory + +```bash +cd /var/www/tractatus +``` + +### 1.3 Run Koha Database Initialization + +```bash +node scripts/init-koha.js +``` + +**Expected Output:** +``` +[KOHA] Initializing database... +✓ Collection 'koha_donations' exists +✓ Created index on status +✓ Created index on frequency +✓ Created index on stripe.subscription_id +✓ Created index on stripe.payment_intent_id +✓ Created index on donor.email +✓ Created index on created_at +✓ Created index on public_acknowledgement +[KOHA] Database initialization complete +``` + +### 1.4 Verify Collection Created + +```bash +mongosh tractatus_prod --eval "db.koha_donations.getIndexes()" +``` + +**Expected:** 10 indexes (7 custom + 3 default) + +--- + +## Phase 2: Environment Configuration + +### 2.1 Update Production .env + +Edit `/var/www/tractatus/.env` and add: + +```bash +# Koha Donation System (Placeholder - not active) +STRIPE_SECRET_KEY=sk_test_PLACEHOLDER_REPLACE_NEXT_WEEK +STRIPE_PUBLISHABLE_KEY=pk_test_PLACEHOLDER_REPLACE_NEXT_WEEK +STRIPE_KOHA_WEBHOOK_SECRET=whsec_PLACEHOLDER_REPLACE_NEXT_WEEK +STRIPE_KOHA_5_PRICE_ID=price_PLACEHOLDER_REPLACE_NEXT_WEEK +STRIPE_KOHA_15_PRICE_ID=price_PLACEHOLDER_REPLACE_NEXT_WEEK +STRIPE_KOHA_50_PRICE_ID=price_PLACEHOLDER_REPLACE_NEXT_WEEK + +# Frontend URL +FRONTEND_URL=https://agenticgovernance.digital +``` + +**Note:** These placeholder values will prevent Stripe operations from executing but allow the code to load. + +### 2.2 Verify Environment Variables + +```bash +grep STRIPE /var/www/tractatus/.env +``` + +--- + +## Phase 3: Deploy Code + +### 3.1 From Local Machine, rsync New Files + +```bash +# Deploy backend files +rsync -avz -e "ssh -i /home/theflow/.ssh/tractatus_deploy" \ + /home/theflow/projects/tractatus/src/config/currencies.config.js \ + /home/theflow/projects/tractatus/src/services/koha.service.js \ + /home/theflow/projects/tractatus/src/controllers/koha.controller.js \ + /home/theflow/projects/tractatus/src/models/Donation.model.js \ + /home/theflow/projects/tractatus/src/routes/koha.routes.js \ + ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/src/ + +# Deploy frontend files +rsync -avz -e "ssh -i /home/theflow/.ssh/tractatus_deploy" \ + /home/theflow/projects/tractatus/public/koha.html \ + /home/theflow/projects/tractatus/public/privacy.html \ + ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/public/ + +rsync -avz -e "ssh -i /home/theflow/.ssh/tractatus_deploy" \ + /home/theflow/projects/tractatus/public/koha/ \ + ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/public/koha/ + +rsync -avz -e "ssh -i /home/theflow/.ssh/tractatus_deploy" \ + /home/theflow/projects/tractatus/public/js/utils/currency.js \ + /home/theflow/projects/tractatus/public/js/components/currency-selector.js \ + /home/theflow/projects/tractatus/public/js/components/footer.js \ + ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/public/js/ + +# Deploy scripts +rsync -avz -e "ssh -i /home/theflow/.ssh/tractatus_deploy" \ + /home/theflow/projects/tractatus/scripts/init-koha.js \ + ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/scripts/ +``` + +### 3.2 Verify Files Deployed + +SSH into production and check: + +```bash +ssh -i /home/theflow/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net \ + "ls -la /var/www/tractatus/src/config/currencies.config.js && \ + ls -la /var/www/tractatus/public/koha.html && \ + ls -la /var/www/tractatus/public/privacy.html" +``` + +--- + +## Phase 4: Add "Coming Soon" Overlay + +### 4.1 Create Coming Soon Overlay Component + +Create `/var/www/tractatus/public/js/components/coming-soon-overlay.js`: + +```javascript +/** + * Coming Soon Overlay + * Displays over Koha pages until Stripe is configured + */ + +(function() { + 'use strict'; + + // Check if we should show the overlay + const shouldShowOverlay = () => { + // Only show on Koha pages + const isKohaPage = window.location.pathname.includes('/koha'); + return isKohaPage; + }; + + // Create and inject overlay + if (shouldShowOverlay()) { + const overlayHTML = ` +
+
+

+ Koha Donation System +

+

+ Coming Soon +

+
+

+ What is Koha? +

+

+ Koha (Māori for "gift") is our upcoming donation system to support the Tractatus Framework. + We're currently finalizing payment processing integration and will launch soon. +

+
+

+ Infrastructure deployed and ready. Payment processing activation in progress. +

+ + Return to Homepage + +

+ Questions? Contact support@agenticgovernance.digital +

+
+
+ `; + + document.body.insertAdjacentHTML('beforeend', overlayHTML); + } +})(); +``` + +### 4.2 Add Overlay to All Koha Pages + +SSH into production and edit these files to add the overlay script: + +```bash +# Add to koha.html, transparency.html, success.html +# Insert before closing tag: + +``` + +**Files to edit:** +- `/var/www/tractatus/public/koha.html` +- `/var/www/tractatus/public/koha/transparency.html` +- `/var/www/tractatus/public/koha/success.html` + +--- + +## Phase 5: Modify API Endpoints for Pre-Launch + +### 5.1 Add Stripe Configuration Check + +Edit `/var/www/tractatus/src/controllers/koha.controller.js`: + +Add at the top of `createCheckout`: + +```javascript +async createCheckout(req, res) { + try { + // Check if Stripe is configured + if (!process.env.STRIPE_SECRET_KEY || + process.env.STRIPE_SECRET_KEY.includes('PLACEHOLDER')) { + return res.status(503).json({ + success: false, + error: 'Donation system not yet active', + message: 'The Koha donation system is currently being configured. Please check back soon.' + }); + } + + // Rest of existing code... +``` + +### 5.2 Add Configuration Check to Transparency Endpoint + +Similar check in `getTransparency` method: + +```javascript +async getTransparency(req, res) { + try { + // Allow transparency data even without Stripe configured + // (will return empty data initially) + + // Rest of existing code... +``` + +--- + +## Phase 6: Restart Production Server + +### 6.1 Restart Node Application + +```bash +ssh -i /home/theflow/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net + +# Stop current process +sudo systemctl stop tractatus + +# Start with new code +sudo systemctl start tractatus + +# Verify running +sudo systemctl status tractatus +``` + +### 6.2 Check Server Logs + +```bash +sudo journalctl -u tractatus -n 50 --no-pager +``` + +**Expected:** No errors, Koha routes loaded + +--- + +## Phase 7: Testing + +### 7.1 Test API Endpoints (Should Return "Not Configured") + +```bash +# Test checkout endpoint +curl -X POST https://agenticgovernance.digital/api/koha/checkout \ + -H "Content-Type: application/json" \ + -d '{ + "amount": 1500, + "currency": "NZD", + "frequency": "monthly", + "tier": "15", + "donor": { + "email": "test@example.com" + } + }' +``` + +**Expected Response:** +```json +{ + "success": false, + "error": "Donation system not yet active", + "message": "The Koha donation system is currently being configured. Please check back soon." +} +``` + +### 7.2 Test Transparency Endpoint + +```bash +curl https://agenticgovernance.digital/api/koha/transparency +``` + +**Expected Response:** +```json +{ + "success": true, + "data": { + "total_received": 0, + "monthly_supporters": 0, + "one_time_donations": 0, + "monthly_recurring_revenue": 0, + "allocation": { + "hosting": 0.30, + "development": 0.40, + "research": 0.20, + "community": 0.10 + }, + "recent_donors": [], + "last_updated": "2025-10-08T..." + } +} +``` + +### 7.3 Test Frontend Pages Show Overlay + +```bash +# Visit in browser: +https://agenticgovernance.digital/koha.html +https://agenticgovernance.digital/koha/transparency +https://agenticgovernance.digital/koha/success +``` + +**Expected:** All pages show "Coming Soon" overlay + +### 7.4 Test Privacy Policy Accessible + +```bash +curl -I https://agenticgovernance.digital/privacy.html +``` + +**Expected:** 200 OK (no overlay on privacy policy) + +--- + +## Phase 8: Documentation Updates + +### 8.1 Update Main README + +Add to production README: + +```markdown +## Koha Donation System Status + +**Status:** Infrastructure Deployed (Awaiting Payment Integration) +**Location:** /koha.html, /koha/transparency, /koha/success +**Database:** koha_donations collection initialized +**Payment Processor:** Stripe (configuration pending) + +The Koha donation system infrastructure is deployed but not yet publicly accessible. +Payment processing integration will be activated next week. +``` + +### 8.2 Create Activation Checklist + +Document at `/var/www/tractatus/docs/KOHA_ACTIVATION_CHECKLIST.md`: + +```markdown +# Koha Activation Checklist + +When Stripe keys are ready: + +1. [ ] Update .env with live Stripe keys +2. [ ] Create Stripe products and prices with currency_options +3. [ ] Set up production webhook endpoint +4. [ ] Remove coming-soon-overlay.js script tags +5. [ ] Remove PLACEHOLDER checks from koha.controller.js +6. [ ] Add navigation links to Koha pages +7. [ ] Test with Stripe test cards +8. [ ] Verify webhook delivery +9. [ ] Test end-to-end donation flow +10. [ ] Restart production server +11. [ ] Monitor first 24 hours of donations +12. [ ] Announce launch +``` + +--- + +## Phase 9: Verification Checklist + +Run through this checklist to verify deployment: + +### Backend Verification + +- [ ] Database collection `koha_donations` exists with 10 indexes +- [ ] Environment variables set (with PLACEHOLDER values) +- [ ] Koha service loads without errors +- [ ] Koha controller loads without errors +- [ ] Koha routes registered in Express +- [ ] API returns 503 "not configured" for checkout requests +- [ ] Transparency API returns empty data structure +- [ ] Server logs show no Koha-related errors + +### Frontend Verification + +- [ ] koha.html deployed and accessible (with overlay) +- [ ] koha/transparency.html deployed (with overlay) +- [ ] koha/success.html deployed (with overlay) +- [ ] privacy.html deployed and accessible (no overlay) +- [ ] Currency selector JS loaded +- [ ] Footer component JS loaded +- [ ] Coming soon overlay displays correctly +- [ ] Return to homepage link works + +### Security Verification + +- [ ] No live Stripe keys in .env +- [ ] No public navigation links to Koha pages +- [ ] Checkout endpoint protected with configuration check +- [ ] No sensitive data in error messages +- [ ] HTTPS enabled for all Koha URLs + +--- + +## Rollback Plan + +If issues occur, rollback steps: + +```bash +# 1. Remove coming-soon-overlay.js from pages +# 2. Disable Koha routes in src/routes/index.js +# 3. Restart server +sudo systemctl restart tractatus + +# 4. Drop koha_donations collection if needed +mongosh tractatus_prod --eval "db.koha_donations.drop()" +``` + +--- + +## Next Week: Stripe Activation + +When live Stripe keys are ready: + +1. Run `docs/KOHA_STRIPE_SETUP.md` (sections 1-7) +2. Update production .env with real keys +3. Remove overlay script tags from HTML files +4. Remove PLACEHOLDER checks from controller +5. Add navigation links to Koha pages +6. Restart server +7. Test end-to-end + +**Estimated Time:** 2-3 hours + +--- + +## Support + +**Issues:** Check `/var/log/tractatus/` logs +**Questions:** john.stroh.nz@pm.me +**Documentation:** /docs/KOHA_STRIPE_SETUP.md + +--- + +**Last Updated:** 2025-10-08 +**Status:** Ready for pre-Stripe deployment +**Next Action:** Execute Phases 1-9 on production server diff --git a/public/js/components/coming-soon-overlay.js b/public/js/components/coming-soon-overlay.js new file mode 100644 index 00000000..5c71113f --- /dev/null +++ b/public/js/components/coming-soon-overlay.js @@ -0,0 +1,102 @@ +/** + * Coming Soon Overlay + * Displays over Koha pages until Stripe is configured + */ + +(function() { + 'use strict'; + + // Check if we should show the overlay + const shouldShowOverlay = () => { + // Only show on Koha pages + const isKohaPage = window.location.pathname.includes('/koha'); + return isKohaPage; + }; + + // Create and inject overlay + if (shouldShowOverlay()) { + const overlayHTML = ` +
+
+

+ Koha Donation System +

+

+ Coming Soon +

+
+

+ What is Koha? +

+

+ Koha (Māori for "gift") is our upcoming donation system to support the Tractatus Framework. + We're currently finalizing payment processing integration and will launch soon. +

+
+

+ Infrastructure deployed and ready. Payment processing activation in progress. +

+ + Return to Homepage + +

+ Questions? Contact support@agenticgovernance.digital +

+
+
+ `; + + document.body.insertAdjacentHTML('beforeend', overlayHTML); + } +})(); diff --git a/public/koha.html b/public/koha.html index eabfa259..a38cf9b9 100644 --- a/public/koha.html +++ b/public/koha.html @@ -325,6 +325,9 @@ + + + + + + + + +