docs: add Koha pre-production deployment quick reference
Provides step-by-step guide for deploying Koha to production without activating Stripe integration. Includes verification checklist, troubleshooting, and activation timeline. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
TheFlow
parent
ae16d64082
commit
6e7df95342
1 changed files with 384 additions and 0 deletions
384
KOHA_PRE_PRODUCTION_SUMMARY.md
Normal file
384
KOHA_PRE_PRODUCTION_SUMMARY.md
Normal file
|
|
@ -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*
|
||||||
Loading…
Add table
Reference in a new issue