mirror of https://github.com/rzmk/learnhouse.git synced 2025-12-18 11:59:26 +00:00

WhiteX d32389a8ef Add LearnHouse Deployment Isolation Toolkit and debugging tools

- Introduced comprehensive documentation for diagnosing and fixing deployment isolation issues between DEV and LIVE instances.
- Implemented enhanced debug API endpoints for deployment verification, URL hardcoding detection, cookie isolation testing, and session configuration checks.
- Created scripts for visual demonstration of cookie isolation, enhanced debugging deployment, and verification of NextAuth cookie isolation.
- Developed a master isolation verification script to run all isolation checks in sequence and summarize results.
- Added detailed README and environment variable guidelines for proper deployment isolation.

2025-10-15 08:01:08 -04:00

4.9 KiB

Raw Blame History

LearnHouse Deployment Isolation Implementation Checklist

This checklist guides you through implementing complete isolation between DEV and LIVE LearnHouse deployments to prevent cross-deployment contamination.

Issue Overview

We've identified that both DEV and LIVE deployments are accessing the same database and contain hardcoded URLs, causing:

Data contamination (same courses appear in both deployments)
Session mixing (logging in on one deployment affects the other)
Inconsistent user experience (clicking links on DEV may lead to LIVE site)

Implementation Checklist

Step 1: Deploy API Changes

Pull the latest code with isolation fixes:
```
git pull origin dev
```
Deploy the enhanced debug tools first:
```
./deploy-enhanced-debug.sh
```
Verify the enhanced debug endpoints are working:
```
ls -la apps/api/src/routers/debug.py
```
Deploy API changes to both environments using your CI/CD system

Step 2: Update Environment Variables

For DEV Environment:

Update database connection string:

LEARNHOUSE_SQL_CONNECTION_STRING=postgresql://learnhouse_dev:YOUR_DEV_PASSWORD@db-dev:5432/learnhouse_dev

Update Redis connection string:

LEARNHOUSE_REDIS_CONNECTION_STRING=redis://default:YOUR_DEV_REDIS_PASSWORD@redis-dev:6379/1

Ensure domain settings are correct:

LEARNHOUSE_DOMAIN=adr-lms.whitex.cloud
LEARNHOUSE_COOKIE_DOMAIN=adr-lms.whitex.cloud
NEXT_PUBLIC_LEARNHOUSE_DOMAIN=adr-lms.whitex.cloud

For LIVE Environment:

Update database connection string:

LEARNHOUSE_SQL_CONNECTION_STRING=postgresql://learnhouse:YOUR_LIVE_PASSWORD@db-live:5432/learnhouse

Update Redis connection string:

LEARNHOUSE_REDIS_CONNECTION_STRING=redis://default:YOUR_LIVE_REDIS_PASSWORD@redis-live:6379/0

Ensure domain settings are correct:

LEARNHOUSE_DOMAIN=edu.adradviser.ro
LEARNHOUSE_COOKIE_DOMAIN=edu.adradviser.ro
NEXT_PUBLIC_LEARNHOUSE_DOMAIN=edu.adradviser.ro

Step 3: Database Infrastructure

Ensure each deployment has its own database server:
- DEV: db-dev
- LIVE: db-live
If using shared infrastructure, ensure logical isolation through server names and proper networking

Step 4: Rebuild & Deploy

Rebuild and deploy both environments with updated environment variables
Restart all services to apply changes

Step 5: Verification

Run the comprehensive isolation verification script:
```
./verify-all-isolation.sh
```
This will:
- Check deployment configuration
- Verify database isolation
- Test cookie isolation
- Check for hardcoded URLs
- Create a visual cookie isolation demo

For more detailed verification, run individual scripts:

./verify-enhanced-isolation.sh      # Basic deployment checks
./verify-db-isolation.sh            # Database-specific checks
./test-nextauth-cookie-isolation.sh # Cookie isolation tests

Test the visual cookie isolation demo:

./create-cookie-demo.sh
# Open the resulting HTML file in a browser

Access debug endpoints directly:
Test in incognito browsers to verify session isolation

Troubleshooting

If isolation issues persist after implementation:

Use the Enhanced Debug Tools:
- Look at the detailed reports in /tmp/learnhouse-isolation-report/
- Run specific tests: ./test-nextauth-cookie-isolation.sh for cookie issues
- Check session configuration: /api/v1/debug/session endpoint
Verify Database Connections:
- Confirm debug endpoints show different database hosts and names
- Check actual database servers to confirm connections come from different sources
- Test with the database isolation script: ./verify-db-isolation.sh
Clear Browser Data:
- Use incognito mode or clear all cookies/cache for proper testing
- Try the cookie isolation demo to visually check cookie behavior
Check Docker Network Isolation:
- Ensure each deployment uses its own Docker network
- Verify hostnames resolve to different IP addresses within containers
Validate URL Patching:
- Run URL debug endpoint to confirm no hardcoded references remain
- Check the enhanced URL report in /api/v1/debug/urls endpoint

For additional help, refer to the full documentation in:

ENHANCED_DEBUG_TOOLS.md - Detailed guide to all debug endpoints
DATABASE_ISOLATION_FIX.md - Database isolation specifics
DEPLOYMENT_TROUBLESHOOTING.md - General deployment troubleshooting
ISOLATION_TOOLKIT_README.md - Overview of all isolation tools

4.9 KiB Raw Blame History