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

3.6 KiB

Raw Blame History

LearnHouse Deployment Isolation Toolkit

This toolkit provides comprehensive tools and documentation for diagnosing and fixing deployment isolation issues between DEV and LIVE LearnHouse instances.

Background

We identified cross-deployment contamination issues between DEV (adr-lms.whitex.cloud) and LIVE (edu.adradviser.ro) deployments, including:

Data contamination (both deployments accessing the same database)
Session mixing (cookies being shared between deployments)
Inconsistent user experience (hardcoded URLs pointing to the wrong environment)

Isolation Toolkit Components

Documentation

ISOLATION_IMPLEMENTATION_CHECKLIST.md
Step-by-step checklist for implementing complete isolation between deployments.
DATABASE_ISOLATION_FIX.md
Detailed explanation of database isolation issues and how to fix them.
DEPLOYMENT_TROUBLESHOOTING.md
Guide for troubleshooting deployment and configuration issues.
ENHANCED_DEBUG_TOOLS.md
Documentation for the enhanced debugging endpoints.
COOLIFY_ENV_VARS.md
Environment variable templates for Coolify deployments.

Debugging Tools

Debug API Endpoints
- /api/v1/debug/deployment - Get detailed deployment configuration
- /api/v1/debug/urls - Scan for hardcoded URLs in the frontend bundle
- /api/v1/debug/cookies - Test cookie isolation between deployments
- /api/v1/debug/session - Verify session configuration
Verification Scripts
- verify-isolation.sh - Basic isolation verification
- verify-enhanced-isolation.sh - Comprehensive isolation checks
- verify-db-isolation.sh - Database-specific isolation verification
- test-nextauth-cookie-isolation.sh - NextAuth cookie isolation test
Visual Demonstration Tools
- create-cookie-demo.sh - Creates an HTML tool to visually demonstrate cookie isolation

Deployment Scripts

deploy-enhanced-debug.sh
Deploys the enhanced debugging endpoints to diagnose isolation issues.
deploy-isolation-fix.sh
Applies the complete isolation fixes to both deployments.

Getting Started

Deploy debugging tools:
```
./deploy-enhanced-debug.sh
```
Run the enhanced isolation verification:
```
./verify-enhanced-isolation.sh
```
Test cookie isolation:
```
./test-nextauth-cookie-isolation.sh
```

Create a visual cookie isolation demo:

./create-cookie-demo.sh
# Then open cookie-isolation-demo.html in your browser

Follow the implementation checklist: See ISOLATION_IMPLEMENTATION_CHECKLIST.md

Key Environment Variables for Isolation

For proper isolation, ensure each deployment has unique values for these variables:

DEV Environment

DEPLOYMENT_NAME=DEV
LEARNHOUSE_SQL_CONNECTION_STRING=postgresql://learnhouse_dev:PASSWORD@db-dev:5432/learnhouse_dev
LEARNHOUSE_COOKIE_DOMAIN=adr-lms.whitex.cloud
NEXT_PUBLIC_LEARNHOUSE_DOMAIN=adr-lms.whitex.cloud
NEXT_PUBLIC_LEARNHOUSE_TOP_DOMAIN=whitex.cloud

LIVE Environment

DEPLOYMENT_NAME=LIVE
LEARNHOUSE_SQL_CONNECTION_STRING=postgresql://learnhouse:PASSWORD@db-live:5432/learnhouse
LEARNHOUSE_COOKIE_DOMAIN=edu.adradviser.ro
NEXT_PUBLIC_LEARNHOUSE_DOMAIN=edu.adradviser.ro
NEXT_PUBLIC_LEARNHOUSE_TOP_DOMAIN=adradviser.ro

Troubleshooting

If you encounter issues during the isolation process, refer to DEPLOYMENT_TROUBLESHOOTING.md.

3.6 KiB Raw Blame History