diff --git a/KOHA_PRE_PRODUCTION_SUMMARY.md b/KOHA_PRE_PRODUCTION_SUMMARY.md new file mode 100644 index 00000000..1155cecc --- /dev/null +++ b/KOHA_PRE_PRODUCTION_SUMMARY.md @@ -0,0 +1,384 @@ +# Koha Pre-Production Deployment - Quick Reference + +**Date:** 2025-10-08 +**Status:** Ready for Production Deployment (Pre-Stripe) +**Goal:** Deploy infrastructure now, activate payments next week + +--- + +## What's Been Prepared + +### ✅ Code Complete +- Multi-currency support (10 currencies) +- Privacy policy and footer component +- Database models and indexes +- API controllers and routes +- Frontend forms and dashboards +- Coming soon overlay for user-facing pages +- Stripe configuration checks + +### ✅ Documentation Complete +- Comprehensive deployment guide: `docs/KOHA_PRODUCTION_DEPLOYMENT.md` +- Stripe setup guide: `docs/KOHA_STRIPE_SETUP.md` +- Automated deployment script: `scripts/deploy-koha-to-production.sh` + +### ✅ Safety Measures +- Coming soon overlay prevents premature user access +- API returns 503 "not configured" when Stripe keys are PLACEHOLDER +- All code deployed but functionality disabled +- No public navigation links to Koha pages + +--- + +## Detailed Next Steps to Deploy to Production + +### Step 1: Deploy Code (5 minutes) + +```bash +# From your local machine +cd /home/theflow/projects/tractatus + +# Run automated deployment script +./scripts/deploy-koha-to-production.sh +``` + +**What this does:** +- Syncs all Koha backend code to production +- Syncs all Koha frontend code to production +- Syncs scripts and utilities +- Shows next manual steps + +### Step 2: SSH into Production (1 minute) + +```bash +ssh -i /home/theflow/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net +cd /var/www/tractatus +``` + +### Step 3: Initialize Database (2 minutes) + +```bash +# Run Koha database initialization +node scripts/init-koha.js +``` + +**Expected output:** +``` +[KOHA] Initializing database... +✓ Collection 'koha_donations' exists +✓ Created index on status +✓ Created index on frequency +... (10 indexes total) +[KOHA] Database initialization complete +``` + +**Verify:** +```bash +mongosh tractatus_prod --eval "db.koha_donations.getIndexes()" | grep name +``` + +Should show 10 indexes. + +### Step 4: Configure Environment Variables (3 minutes) + +```bash +# Edit production .env +nano /var/www/tractatus/.env +``` + +**Add these lines at the end:** + +```bash +# ================================================== +# Koha Donation System (Pre-Production) +# These are PLACEHOLDER values until Stripe keys ready +# ================================================== + +# Stripe API Keys (PLACEHOLDERS) +STRIPE_SECRET_KEY=sk_test_PLACEHOLDER_REPLACE_NEXT_WEEK +STRIPE_PUBLISHABLE_KEY=pk_test_PLACEHOLDER_REPLACE_NEXT_WEEK + +# Stripe Webhook Secret (PLACEHOLDER) +STRIPE_KOHA_WEBHOOK_SECRET=whsec_PLACEHOLDER_REPLACE_NEXT_WEEK + +# Stripe Price IDs for Monthly Tiers (PLACEHOLDERS) +STRIPE_KOHA_5_PRICE_ID=price_PLACEHOLDER_5_REPLACE_NEXT_WEEK +STRIPE_KOHA_15_PRICE_ID=price_PLACEHOLDER_15_REPLACE_NEXT_WEEK +STRIPE_KOHA_50_PRICE_ID=price_PLACEHOLDER_50_REPLACE_NEXT_WEEK + +# Frontend URL (PRODUCTION) +FRONTEND_URL=https://agenticgovernance.digital +``` + +Save and exit (`Ctrl+X`, `Y`, `Enter`) + +**Verify:** +```bash +grep STRIPE /var/www/tractatus/.env +``` + +### Step 5: Restart Production Server (1 minute) + +```bash +# Restart the application +sudo systemctl restart tractatus + +# Verify it started successfully +sudo systemctl status tractatus + +# Check logs for errors +sudo journalctl -u tractatus -n 50 --no-pager | grep -i koha +``` + +**Expected in logs:** +``` +Koha routes registered +InstructionPersistenceClassifier initialized +Server running on port 9000 +``` + +### Step 6: Test API Endpoints (5 minutes) + +**Test 1: Transparency endpoint (should work, return empty data)** + +```bash +curl -s https://agenticgovernance.digital/api/koha/transparency | jq '.' +``` + +**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..." + } +} +``` + +**Test 2: Checkout endpoint (should return "not configured")** + +```bash +curl -X POST https://agenticgovernance.digital/api/koha/checkout \ + -H "Content-Type: application/json" \ + -d '{ + "amount": 1500, + "currency": "NZD", + "frequency": "monthly", + "tier": "15", + "donor": { + "name": "Test User", + "email": "test@example.com" + } + }' | jq '.' +``` + +**Expected response:** +```json +{ + "success": false, + "error": "Donation system not yet active", + "message": "The Koha donation system is currently being configured. Please check back soon." +} +``` + +✅ **Perfect!** This means the safety check is working. + +### Step 7: Test Frontend Pages (2 minutes) + +Open browser and visit: + +1. **https://agenticgovernance.digital/koha.html** + - Should show "Coming Soon" overlay + - Should NOT allow form interaction + +2. **https://agenticgovernance.digital/koha/transparency** + - Should show "Coming Soon" overlay + - Should show return to homepage button + +3. **https://agenticgovernance.digital/privacy.html** + - Should load normally (NO overlay) + - Privacy policy should be readable + +### Step 8: Verify No Public Access (1 minute) + +Check that Koha is NOT linked from main site: + +```bash +# Check if navbar has Koha links (should not) +curl -s https://agenticgovernance.digital/ | grep -i koha +``` + +**Expected:** No results (Koha not in public navigation yet) + +--- + +## Verification Checklist + +After completing Steps 1-8, verify: + +- [ ] Database collection `koha_donations` exists with 10 indexes +- [ ] Environment variables set with PLACEHOLDER values +- [ ] Server restarted without errors +- [ ] Transparency API returns empty data (not error) +- [ ] Checkout API returns 503 "not configured" +- [ ] koha.html shows coming soon overlay +- [ ] transparency.html shows coming soon overlay +- [ ] success.html shows coming soon overlay +- [ ] privacy.html loads normally (no overlay) +- [ ] No public navigation links to Koha pages +- [ ] Server logs show no Koha-related errors + +--- + +## What Happens Next Week + +When you have live Stripe keys ready: + +### Quick Activation (2-3 hours) + +1. **Update .env with real Stripe keys** (10 min) + - Replace all PLACEHOLDER values + - Create Stripe products/prices with currency_options + - Create webhook endpoint + +2. **Remove safety measures** (5 min) + - Delete overlay script tags from HTML files + - Remove PLACEHOLDER check from controller + - Verify code changes + +3. **Add navigation links** (5 min) + - Update navbar to include Koha link + - Update footer with donation link + +4. **Test thoroughly** (30 min) + - Test checkout flow with test cards + - Verify webhook delivery + - Test all 10 currencies + - Test monthly and one-time donations + - Verify transparency dashboard updates + +5. **Restart and monitor** (5 min) + - Restart production server + - Monitor logs for 15 minutes + - Watch for successful test donation + +6. **Announce launch** (30 min) + - Update website with donation call-to-action + - Social media announcement (optional) + - Email supporters (optional) + +### Detailed Activation Guide + +See: `docs/KOHA_STRIPE_SETUP.md` (sections 1-7) + +--- + +## Troubleshooting + +### Issue: Server won't start after deployment + +```bash +# Check for syntax errors +cd /var/www/tractatus +node -c src/services/koha.service.js +node -c src/controllers/koha.controller.js + +# Check logs +sudo journalctl -u tractatus -n 100 --no-pager +``` + +### Issue: API returns 404 for Koha endpoints + +```bash +# Verify routes file deployed +ls -la /var/www/tractatus/src/routes/koha.routes.js + +# Verify routes registered +grep -r "koha" /var/www/tractatus/src/routes/index.js +``` + +### Issue: Coming soon overlay not showing + +```bash +# Verify overlay script deployed +ls -la /var/www/tractatus/public/js/components/coming-soon-overlay.js + +# Check browser console for JS errors +# Open DevTools (F12) and check Console tab +``` + +### Issue: Database collection not created + +```bash +# Connect to MongoDB +mongosh tractatus_prod + +# Check collections +show collections + +# Check if init script ran +db.koha_donations.countDocuments() + +# Re-run if needed +exit +node scripts/init-koha.js +``` + +--- + +## Key Files Reference + +**Deployment Guide:** +- `/home/theflow/projects/tractatus/docs/KOHA_PRODUCTION_DEPLOYMENT.md` + +**Stripe Setup Guide:** +- `/home/theflow/projects/tractatus/docs/KOHA_STRIPE_SETUP.md` + +**Deployment Script:** +- `/home/theflow/projects/tractatus/scripts/deploy-koha-to-production.sh` + +**Database Init Script:** +- `/home/theflow/projects/tractatus/scripts/init-koha.js` + +**Key Backend Files:** +- `src/services/koha.service.js` - Stripe integration logic +- `src/controllers/koha.controller.js` - API endpoints (has PLACEHOLDER check) +- `src/models/Donation.model.js` - Database schema +- `src/config/currencies.config.js` - Currency conversion + +**Key Frontend Files:** +- `public/koha.html` - Main donation form +- `public/koha/transparency.html` - Public dashboard +- `public/koha/success.html` - Thank you page +- `public/js/components/coming-soon-overlay.js` - Overlay (remove for activation) + +--- + +## Summary + +**Current Status:** +- ✅ All code committed and ready +- ✅ Documentation complete +- ✅ Automated deployment script ready +- ⏳ Awaiting deployment to production (Steps 1-8 above) +- ⏳ Awaiting Stripe keys next week + +**Total Deployment Time:** ~20 minutes +**Total Activation Time (when Stripe ready):** 2-3 hours + +**Contact:** john.stroh.nz@pm.me + +--- + +*Last Updated: 2025-10-08*