tractatus/docs/STRIPE_LIVE_MODE_DEPLOYMENT.md

Stripe Live Mode Deployment - Step-by-Step Guide

Project: Tractatus Koha Donation System Date: 2025-10-18 Current Status: Test Mode Complete ✅ Next Step: Production Deployment

---

⚠️ Pre-Deployment Checklist

Before switching to live mode, verify:

• ✅ Test mode fully working in browser
• ✅ Webhooks tested and receiving events
• ✅ Donations recording in database correctly
• ✅ Email addresses valid (for receipt emails)
• ⚠️ Bank account connected to Stripe (required for payouts)
• ⚠️ Business verification complete (may be required)

---

Phase 1: Stripe Dashboard - Switch to Live Mode

Step 1.1: Access Stripe Dashboard

1. Go to https://dashboard.stripe.com
2. Log in with your Stripe account credentials
3. Click the "Test mode" toggle in the top-right corner
4. Switch to "Live mode" (toggle should turn blue/live color)

⚠️ IMPORTANT: From this point forward, you're working with real money and real customers.

Step 1.2: Get Live API Keys

1. In Live Mode, click Developers → API keys in the left sidebar
2. You'll see two keys:
   • Publishable key (starts with pk_live_)
   • Secret key (starts with sk_live_)
3. Click "Reveal test key" next to Secret key
4. Copy both keys and save them securely (you'll need them soon)

pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

🔒 Security: Never commit live keys to Git. Keep them in .env only.

---

Phase 2: Create Production Webhook

Step 2.1: Create Webhook Endpoint

1. Still in Live Mode, go to Developers → Webhooks
2. Click "Add endpoint"
3. Fill in the form:

Endpoint URL:

https://agenticgovernance.digital/api/koha/webhook

Description:

Tractatus Koha - Production Donations

Events to send: Select these 8 events:

• ✅ checkout.session.completed
• ✅ payment_intent.succeeded
• ✅ payment_intent.payment_failed
• ✅ invoice.paid
• ✅ invoice.payment_failed
• ✅ customer.subscription.created
• ✅ customer.subscription.updated
• ✅ customer.subscription.deleted

4. Click "Add endpoint"

Step 2.2: Get Webhook Signing Secret

1. After creating the endpoint, you'll see it in the list
2. Click on the endpoint to open details
3. In the "Signing secret" section, click "Reveal"
4. Copy the signing secret (starts with whsec_)

whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Save this secret - you'll add it to .env in the next phase.

---

Phase 3: Update Production Environment Variables

Step 3.1: Create Production .env File

⚠️ DO NOT modify your local .env file yet!

Create a new file for production environment variables:

# Location: /home/theflow/projects/tractatus/.env.production

Content:

# Production Environment Variables for Tractatus
NODE_ENV=production
PORT=9000
APP_NAME=Tractatus

# MongoDB (Production)
MONGODB_URI=mongodb://localhost:27017/tractatus_prod
MONGODB_PORT=27017
MONGODB_DB=tractatus_prod

# JWT Authentication
JWT_SECRET=[REDACTED]
JWT_EXPIRY=7d

# Admin
ADMIN_EMAIL=john.stroh.nz@pm.me

# Claude API
CLAUDE_API_KEY=[REDACTED - key rotated 2025-10-21]
CLAUDE_MODEL=claude-sonnet-4-5-20250929
CLAUDE_MAX_TOKENS=4096

# Logging
LOG_LEVEL=info
LOG_FILE=logs/app.log

# Feature Flags
ENABLE_AI_CURATION=true
ENABLE_MEDIA_TRIAGE=false
ENABLE_CASE_SUBMISSIONS=false

# Security
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# Koha Donation System - LIVE MODE
# ⚠️ REPLACE WITH YOUR ACTUAL LIVE KEYS FROM STRIPE DASHBOARD
STRIPE_SECRET_KEY=sk_live_PASTE_YOUR_LIVE_SECRET_KEY_HERE
STRIPE_PUBLISHABLE_KEY=pk_live_PASTE_YOUR_LIVE_PUBLISHABLE_KEY_HERE
STRIPE_KOHA_WEBHOOK_SECRET=whsec_PASTE_YOUR_LIVE_WEBHOOK_SECRET_HERE

# Stripe Product and Price IDs (SAME AS TEST MODE)
STRIPE_KOHA_PRODUCT_ID=prod_TFusJH4Q3br8gA
STRIPE_KOHA_5_PRICE_ID=price_1SJP2fGhfAwOYBrf9yrf0q8C
STRIPE_KOHA_15_PRICE_ID=price_1SJP2fGhfAwOYBrfNc6Nfjyj
STRIPE_KOHA_50_PRICE_ID=price_1SJP2fGhfAwOYBrf0A62TOpf

# Frontend URL (Production)
FRONTEND_URL=https://agenticgovernance.digital

Step 3.2: Replace Placeholder Values

1. Open .env.production in your editor
2. Replace PASTE_YOUR_LIVE_SECRET_KEY_HERE with your actual live secret key
3. Replace PASTE_YOUR_LIVE_PUBLISHABLE_KEY_HERE with your actual live publishable key
4. Replace PASTE_YOUR_LIVE_WEBHOOK_SECRET_HERE with your actual webhook signing secret
5. Save the file

⚠️ IMPORTANT: Verify there are NO test keys (sk_test_ or pk_test_) in this file!

---

Phase 4: Test Locally with Live Keys (OPTIONAL BUT RECOMMENDED)

Before deploying to production, test with live keys locally using a real card.

Step 4.1: Backup Current Test .env

cp /home/theflow/projects/tractatus/.env /home/theflow/projects/tractatus/.env.test-backup

Step 4.2: Temporarily Use Live Keys Locally

cp /home/theflow/projects/tractatus/.env.production /home/theflow/projects/tractatus/.env

Step 4.3: Restart Server with Live Keys

# Kill existing server
pkill -9 -f "node.*server.js"

# Start with live keys
cd /home/theflow/projects/tractatus
npm start > logs/server-live-test.log 2>&1 &

# Wait for startup
sleep 4

# Check server health
curl http://localhost:9000/health

Step 4.4: Make Test Donation with REAL CARD

⚠️ You will be charged real money for this test!

1. Go to http://localhost:9000/koha.html
2. Select the Foundation tier ($5 NZD)
3. Enter YOUR real email address (you'll get a receipt)
4. Click submit
5. Use a REAL credit card (not 4242...)
6. Complete the payment

Expected cost: $5 NZD (~$3 USD depending on your card)

Step 4.5: Verify Test Donation

Check the server logs:

tail -20 logs/server-live-test.log | grep KOHA

Expected output:

[KOHA] Creating checkout session: monthly donation of NZD $5 (NZD $5)
[KOHA] Checkout session created: cs_live_...
[KOHA] Processing webhook event: checkout.session.completed
[KOHA] Donation recorded: NZD $5 (NZD $5)

Check Stripe Dashboard:

1. Go to https://dashboard.stripe.com (Live Mode)
2. Click Payments
3. You should see your $5 test payment
4. Status should be Succeeded

Step 4.6: Cancel Test Subscription (Optional)

If you don't want to continue the monthly subscription:

1. Go to Stripe Dashboard → Customers
2. Find your test customer
3. Click on the subscription
4. Click "Cancel subscription"
5. Confirm cancellation

Step 4.7: Restore Test Environment

After successful testing:

# Restore test mode .env
cp /home/theflow/projects/tractatus/.env.test-backup /home/theflow/projects/tractatus/.env

# Restart server in test mode
pkill -9 -f "node.*server.js"
npm start > logs/server-restart.log 2>&1 &

---

Phase 5: Deploy to Production Server

Step 5.1: Connect to Production Server

ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net

Step 5.2: Backup Current Production .env

cd /var/www/tractatus
sudo cp .env .env.backup-$(date +%Y%m%d-%H%M%S)

Step 5.3: Update Production .env

Option A: Edit directly on server (Recommended)

sudo nano /var/www/tractatus/.env

Update these lines:

# Change from test to live keys
STRIPE_SECRET_KEY=sk_live_YOUR_LIVE_SECRET_KEY
STRIPE_PUBLISHABLE_KEY=pk_live_YOUR_LIVE_PUBLISHABLE_KEY
STRIPE_KOHA_WEBHOOK_SECRET=whsec_YOUR_LIVE_WEBHOOK_SECRET

# Update database to production
MONGODB_DB=tractatus_prod

# Update frontend URL
FRONTEND_URL=https://agenticgovernance.digital

Save and exit (Ctrl+X, Y, Enter)

Option B: Upload .env.production from local

# From your LOCAL machine:
scp -i ~/.ssh/tractatus_deploy \
  /home/theflow/projects/tractatus/.env.production \
  ubuntu@vps-93a693da.vps.ovh.net:/tmp/env-production

# Then on the server:
sudo mv /tmp/env-production /var/www/tractatus/.env
sudo chown ubuntu:ubuntu /var/www/tractatus/.env
sudo chmod 600 /var/www/tractatus/.env

Step 5.4: Verify .env File

# Check that live keys are present (without revealing them)
grep "STRIPE_SECRET_KEY=sk_live" /var/www/tractatus/.env && echo "✅ Live secret key configured"
grep "STRIPE_PUBLISHABLE_KEY=pk_live" /var/www/tractatus/.env && echo "✅ Live publishable key configured"
grep "STRIPE_KOHA_WEBHOOK_SECRET=whsec" /var/www/tractatus/.env && echo "✅ Webhook secret configured"

All three checks should print ✅.

Step 5.5: Restart Production Server

# Check current status
sudo systemctl status tractatus

# Restart service
sudo systemctl restart tractatus

# Wait a moment
sleep 3

# Verify it started successfully
sudo systemctl status tractatus

# Check logs for errors
sudo journalctl -u tractatus -n 50 --no-pager

Expected output: Service should be "active (running)"

Step 5.6: Test Production Endpoint

From your local machine:

curl https://agenticgovernance.digital/health

Expected: {"status":"ok","timestamp":"2025-10-18T..."}

---

Phase 6: Verify Production Donation System

Step 6.1: Test Donation Form

1. Open https://agenticgovernance.digital/koha.html in browser
2. Form should load correctly
3. All translations working (English, German, French)

Step 6.2: Make First Real Donation

⚠️ This will charge you real money!

1. Select Foundation tier ($5 NZD) (smallest amount)
2. Enter YOUR real email
3. Enter your name (optional)
4. Click "Offer Koha — Join Our Community"
5. You should be redirected to Stripe Checkout (live mode)
6. Use a REAL credit card
7. Complete payment

Step 6.3: Verify Webhook Delivery

1. Go to Stripe Dashboard (Live Mode) → Developers → Webhooks
2. Click on your production webhook endpoint
3. Click "Recent deliveries" tab
4. You should see your events with 200 OK status:
   • checkout.session.completed ✅
   • payment_intent.succeeded ✅
   • customer.subscription.created ✅

If you see red failed indicators, there's a problem. Check server logs.

Step 6.4: Check Production Database

SSH to server:

ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net

Check donations:

mongosh mongodb://localhost:27017/tractatus_prod --quiet --eval "
  db.koha_donations.find({}, {
    donor: 1,
    amount: 1,
    status: 1,
    created_at: 1
  }).sort({created_at: -1}).limit(3)
"

You should see your test donation with:

• Status: "completed"
• Amount: 500 (cents)
• Your email

Step 6.5: Verify Receipt Email

Check your email inbox for:

• Subject: "Thank you for your Koha to Tractatus"
• From: Stripe or your configured email
• Contains donation amount and details

---

Phase 7: Monitoring & Maintenance

Daily Checks (First Week)

1. Check Stripe Dashboard daily:

   • Go to https://dashboard.stripe.com
   • Review Payments for new donations
   • Check Webhooks for failed deliveries

2. Monitor server logs:

ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net
sudo journalctl -u tractatus -f

3. Check database:

mongosh mongodb://localhost:27017/tractatus_prod --quiet --eval "
  print('Total donations:', db.koha_donations.countDocuments());
  print('Completed:', db.koha_donations.countDocuments({status: 'completed'}));
  print('Pending:', db.koha_donations.countDocuments({status: 'pending'}));
"

Webhook Failure Recovery

If webhooks fail (show red in Stripe Dashboard):

1. Check server status:

sudo systemctl status tractatus

2. Check server logs:

sudo journalctl -u tractatus -n 100 --no-pager | grep -i "webhook\|koha"

3. Verify endpoint is accessible:

curl -X POST https://agenticgovernance.digital/api/koha/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

4. Retry failed webhooks:
   • Go to Stripe Dashboard → Webhooks → Your endpoint
   • Click on failed event
   • Click "Resend event"

---

Phase 8: Rollback Plan (If Things Go Wrong)

If you encounter critical issues in production:

Emergency Rollback to Test Mode

1. SSH to production server:

ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net

2. Restore backup .env:

sudo cp /var/www/tractatus/.env.backup-TIMESTAMP /var/www/tractatus/.env

3. Restart server:

sudo systemctl restart tractatus

4. Verify:

curl https://agenticgovernance.digital/health

5. Disable webhook in Stripe Dashboard:
   • Go to Developers → Webhooks
   • Click on production endpoint
   • Click "Disable endpoint"

---

Summary Checklist

Before declaring production ready:

• Live API keys obtained from Stripe Dashboard
• Production webhook created and secret obtained
• .env.production file created with live keys
• Tested locally with real card ($5 test donation)
• Test donation succeeded in Stripe Dashboard
• Webhook events delivered successfully (200 OK)
• Production .env updated on server
• Production server restarted successfully
• First production donation completed successfully
• Donation recorded in database
• Receipt email received
• Monitoring plan in place

---

Support & Troubleshooting

Stripe Support:

• Dashboard: https://dashboard.stripe.com
• Documentation: https://stripe.com/docs
• Support: https://support.stripe.com

Server Issues:

# Check logs
sudo journalctl -u tractatus -n 100 --no-pager

# Check server status
sudo systemctl status tractatus

# Restart if needed
sudo systemctl restart tractatus

Database Issues:

# Check MongoDB status
sudo systemctl status mongod

# Check database
mongosh mongodb://localhost:27017/tractatus_prod

---

Last Updated: 2025-10-18 Version: 1.0 Status: Ready for Production Deployment

⚠️ IMPORTANT: Test thoroughly before announcing to users!