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