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
653c5959f4
commit
a4e65a3d8d
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