moreminimore-marketing/.github/INSTALLATION.md

ALwrity Quick Start Guide

Complete setup guide for running ALwrity locally after cloning from GitHub.

🎯 Prerequisites

Before you begin, ensure you have:

• Node.js 16+ and npm installed (Download)
• Python 3.8+ installed (Download)
• Git installed (Download)
• Clerk Account (Sign up)
• API Keys (Gemini, CopilotKit, etc.)

🚀 Quick Setup (Automated)

Option A: Windows

# 1. Clone the repository
git clone https://github.com/AJaySi/ALwrity.git
cd ALwrity

# 2. Run automated setup
.\setup_alwrity.bat

Option B: macOS/Linux

# 1. Clone the repository
git clone https://github.com/AJaySi/ALwrity.git
cd ALwrity

# 2. Make script executable and run
chmod +x setup_alwrity.sh
./setup_alwrity.sh

📝 Manual Setup (Step-by-Step)

Step 1: Clone Repository

git clone https://github.com/AJaySi/ALwrity.git
cd ALwrity

Step 2: Backend Setup

# Navigate to backend
cd backend

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
cp env_template.txt .env

# Edit .env and add your API keys:
# - CLERK_SECRET_KEY
# - CLERK_PUBLISHABLE_KEY
# - GEMINI_API_KEY (optional, can be provided in UI)

# Initialize database
python scripts/create_subscription_tables.py
python scripts/cleanup_alpha_plans.py

# Return to root
cd ..

Step 3: Frontend Setup

# Navigate to frontend
cd frontend

# Clean install (important!)
rm -rf node_modules package-lock.json  # macOS/Linux
# OR for Windows PowerShell:
# Remove-Item -Recurse -Force node_modules, package-lock.json -ErrorAction SilentlyContinue

# Install dependencies (THIS IS CRITICAL - DO NOT SKIP!)
npm install

# Create .env file
cp env_template.txt .env

# Edit .env and add:
# REACT_APP_CLERK_PUBLISHABLE_KEY=<your-clerk-publishable-key>
# REACT_APP_API_BASE_URL=http://localhost:8000

# Build the project (validates everything compiles)
npm run build

# Return to root
cd ..

Step 4: Start the Application

Terminal 1 - Backend:

cd backend
python app.py

Terminal 2 - Frontend:

cd frontend
npm start

Step 5: Access the Application

• Frontend UI: http://localhost:3000
• Backend API Docs: http://localhost:8000/api/docs
• Health Check: http://localhost:8000/health

🐛 Troubleshooting Common Issues

Issue 1: "CopilotSidebar is not exported" Error

Cause: Did not run npm install in frontend directory

Fix:

cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build
npm start

Issue 2: "Module not found" (Python)

Cause: Did not install Python dependencies or activate virtual environment

Fix:

cd backend
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

Issue 3: "CORS Error" in Browser

Cause: Backend not running or frontend connecting to wrong URL

Fix:

1. Ensure backend is running on http://localhost:8000
2. Check frontend/.env has REACT_APP_API_BASE_URL=http://localhost:8000
3. Restart both frontend and backend

Issue 4: "Clerk Publishable Key Missing"

Cause: Frontend .env file not configured

Fix:

cd frontend
# Edit .env file and add:
# REACT_APP_CLERK_PUBLISHABLE_KEY=pk_test_xxx...

Issue 5: "Database Error" or "Subscription Plans Not Found"

Cause: Database tables not created

Fix:

cd backend
python scripts/create_subscription_tables.py
python scripts/cleanup_alpha_plans.py

Issue 6: "Port Already in Use"

Backend (8000):

# Find and kill process using port 8000
# Windows:
netstat -ano | findstr :8000
taskkill /PID <process_id> /F

# macOS/Linux:
lsof -ti:8000 | xargs kill -9

Frontend (3000):

# Find and kill process using port 3000
# Windows:
netstat -ano | findstr :3000
taskkill /PID <process_id> /F

# macOS/Linux:
lsof -ti:3000 | xargs kill -9

✅ Verification Checklist

After setup, verify:

• Backend health check returns 200 OK: curl http://localhost:8000/health
• Frontend loads without errors
• Can sign in with Clerk authentication
• Pricing page loads with 4 subscription tiers (Free, Basic, Pro, Enterprise)
• Can navigate to onboarding after selecting a plan

📚 Environment Variables Required

Backend (.env)

# Required for authentication
CLERK_SECRET_KEY=sk_test_xxx...
CLERK_PUBLISHABLE_KEY=pk_test_xxx...

# Optional (can be provided via UI in Step 1 of onboarding)
GEMINI_API_KEY=AIzaSy...
EXA_API_KEY=xxx...
COPILOTKIT_API_KEY=xxx...

# Development settings
DISABLE_AUTH=false
DEPLOY_ENV=local

Frontend (.env)

# Required
REACT_APP_CLERK_PUBLISHABLE_KEY=pk_test_xxx...

# Optional
REACT_APP_API_BASE_URL=http://localhost:8000
REACT_APP_COPILOTKIT_API_KEY=xxx...

🎯 First-Time User Flow

After setup:

1. Start both servers (backend + frontend)
2. Navigate to http://localhost:3000
3. Sign in with Clerk
4. Select subscription plan (Free or Basic for alpha testing)
5. Complete onboarding (6 steps):
   • Step 1: API Keys
   • Step 2: Website Analysis
   • Step 3: Competitor Research
   • Step 4: Persona Generation
   • Step 5: Research Preferences
   • Step 6: Final Review
6. Access dashboard with all features unlocked

🆘 Getting Help

If you encounter issues:

1. Check logs: Both terminal windows show detailed error messages
2. GitHub Issues: https://github.com/AJaySi/ALwrity/issues
3. Documentation: See docs/ directory for detailed guides
4. Common Issues: See docs/GITHUB_ISSUE_291_FIX.md for CopilotSidebar error

📖 Additional Documentation

• Onboarding System: docs/API_KEY_MANAGEMENT_ARCHITECTURE.md
• Subscription System: docs/Billing_Subscription/SUBSCRIPTION_IMPLEMENTATION_SUMMARY.md
• Deployment Guide: DEPLOY_ENV_REFERENCE.md
• API Key Management: docs/API_KEY_INJECTION_EXPLAINED.md

---

Need help? Open an issue on GitHub: https://github.com/AJaySi/ALwrity/issues