tractatus/KOHA_PRE_PRODUCTION_SUMMARY.md

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)

# 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)

ssh -i /home/theflow/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net
cd /var/www/tractatus

Step 3: Initialize Database (2 minutes)

# 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:

mongosh tractatus_prod --eval "db.koha_donations.getIndexes()" | grep name

Should show 10 indexes.

Step 4: Configure Environment Variables (3 minutes)

# Edit production .env
nano /var/www/tractatus/.env

Add these lines at the end:

# ==================================================
# 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:

grep STRIPE /var/www/tractatus/.env

Step 5: Restart Production Server (1 minute)

# 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)

curl -s https://agenticgovernance.digital/api/koha/transparency | jq '.'

Expected response:

{
  "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")

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:

{
  "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:

# 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

# 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

# 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

# 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

# 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