From e7b2428550f0bd8311d7e24eeb15998a54370361 Mon Sep 17 00:00:00 2001
From: naaa760 <neh6a683@gmail.com>
Date: Fri, 14 Nov 2025 09:39:31 +0530
Subject: [PATCH 1/6] docs: add comprehensive local development guide

---
 LOCAL_DEVELOPMENT.md | 204 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 LOCAL_DEVELOPMENT.md

diff --git a/LOCAL_DEVELOPMENT.md b/LOCAL_DEVELOPMENT.md
new file mode 100644
index 000000000..d15d042e9
--- /dev/null
+++ b/LOCAL_DEVELOPMENT.md
@@ -0,0 +1,204 @@
+# Local Development Guide for Echo
+
+This guide will help you get Echo running locally on your machine.
+
+## Quick Start (Automated Setup)
+
+```bash
+# Clone the repository
+git clone https://github.com/Merit-Systems/echo.git
+cd echo
+
+# Run the automated setup script
+./scripts/setup-local.sh
+
+# Start the development servers
+pnpm dev
+```
+
+That's it! Visit http://localhost:3000 to access Echo.
+
+## Prerequisites
+
+Before starting, ensure you have the following installed:
+
+- **Node.js** (v18.0.0 or higher) - [Install Node.js](https://nodejs.org/)
+- **pnpm** (v10.0.0 or higher) - Install with: `npm install -g pnpm@10.11.0`
+- **Docker** and **Docker Compose** - [Install Docker](https://docs.docker.com/get-docker/)
+- **Git** - [Install Git](https://git-scm.com/downloads)
+
+## Manual Step-by-Step Setup
+
+### 1. Clone and Install Dependencies
+
+```bash
+# Clone the repository
+git clone https://github.com/Merit-Systems/echo.git
+cd echo
+
+# Install all dependencies
+pnpm install
+```
+
+### 2. Set Up Environment Variables
+
+#### For Echo Control (Dashboard)
+
+```bash
+# Navigate to the control package
+cd packages/app/control
+
+# Create .env file from the example
+cp .env.example .env
+
+# Generate AUTH_SECRET automatically
+cd ../../../
+pnpm local-setup
+cd packages/app/control
+```
+
+#### For Echo Server (Proxy)
+
+```bash
+# Navigate to the server package
+cd ../server
+
+# Create .env file
+cat > .env << 'EOF'
+# Database (uses same PostgreSQL as control)
+DATABASE_URL="postgresql://echo_user:echo_password@localhost:5469/echo_control_v2?schema=public"
+
+# Server Configuration
+PORT=3069
+NODE_ENV=development
+
+# API Keys (optional for local development)
+OPENAI_API_KEY=""
+ANTHROPIC_API_KEY=""
+GEMINI_API_KEY=""
+EOF
+
+cd ../../..
+```
+
+### 3. Start the Database
+
+Make sure Docker is running, then:
+
+```bash
+# From the echo-control directory
+cd packages/app/control
+
+# Start PostgreSQL container
+docker compose -f docker-local-db.yml up -d
+
+# Wait for database to be ready (about 5-10 seconds)
+sleep 10
+
+# Run database migrations
+npx prisma generate
+npx prisma db push
+
+cd ../../..
+```
+
+### 4. Start Development Servers
+
+From the root directory:
+
+```bash
+# This will start both Echo Control (port 3000) and Echo Server (port 3069)
+pnpm dev
+```
+
+## Accessing the Applications
+
+Once everything is running:
+
+- **Echo Control Dashboard**: http://localhost:3000
+- **Echo Server API**: http://localhost:3069
+
+### Local Authentication
+
+In development mode, you can use the "Local User" credential provider:
+1. Go to http://localhost:3000/login
+2. Click "Local User" 
+3. You'll be logged in as a test user
+
+## Common Issues and Solutions
+
+### Issue: Docker daemon not running
+
+**Error**: `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`
+
+**Solution**: 
+- On macOS: Start Docker Desktop
+- On Linux: `sudo systemctl start docker`
+- On Windows: Start Docker Desktop
+
+### Issue: Port already in use
+
+**Error**: `Error: listen EADDRINUSE: address already in use :::3000`
+
+**Solution**:
+```bash
+# Find process using the port
+lsof -i :3000
+# Kill the process
+kill -9 <PID>
+```
+
+### Issue: Database connection failed
+
+**Error**: `Can't reach database server at localhost:5469`
+
+**Solution**:
+```bash
+# Check if PostgreSQL container is running
+docker ps | grep echo-control-postgres
+
+# If not running, start it:
+cd packages/app/control
+docker compose -f docker-local-db.yml up -d
+```
+
+### Issue: Missing environment variables
+
+**Error**: `Missing required environment variables`
+
+**Solution**: Make sure you've completed step 2 and created both .env files with the required variables.
+
+## Useful Commands
+
+```bash
+# View database contents
+cd packages/app/control
+npx prisma studio
+
+# Reset database
+npx prisma migrate reset
+
+# View Docker logs
+docker logs echo-control-postgres-v2
+
+# Stop PostgreSQL container
+docker compose -f docker-local-db.yml down
+
+# Stop and remove all data
+docker compose -f docker-local-db.yml down -v
+```
+
+## Next Steps
+
+1. Create an Echo app in the dashboard
+2. Generate an API key
+3. Try one of our templates:
+   ```bash
+   pnpx echo-start@latest my-echo-app
+   ```
+
+## Need Help?
+
+- Join our [Discord](https://discord.gg/merit)
+- Check the [documentation](https://echo.merit.systems/docs)
+- Open an [issue](https://github.com/Merit-Systems/echo/issues)

From dc90b9b85a2004cec6eea49578d5fec7a22a25a6 Mon Sep 17 00:00:00 2001
From: naaa760 <neh6a683@gmail.com>
Date: Fri, 14 Nov 2025 10:14:48 +0530
Subject: [PATCH 2/6] feat: add automated local setup script

---
 scripts/setup-local.sh | 132 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100755 scripts/setup-local.sh

diff --git a/scripts/setup-local.sh b/scripts/setup-local.sh
new file mode 100755
index 000000000..647d6973d
--- /dev/null
+++ b/scripts/setup-local.sh
@@ -0,0 +1,132 @@
+#!/bin/bash
+# setup-local.sh - Automated local development setup for Echo
+
+set -e
+
+echo "🚀 Setting up Echo for local development..."
+
+# Check prerequisites
+echo "📋 Checking prerequisites..."
+
+# Check Node.js
+if ! command -v node &> /dev/null; then
+    echo "❌ Node.js is not installed. Please install Node.js 18+ first."
+    echo "   Visit: https://nodejs.org/"
+    exit 1
+fi
+
+NODE_VERSION=$(node -v | cut -d'.' -f1 | sed 's/v//')
+if [ "$NODE_VERSION" -lt 18 ]; then
+    echo "❌ Node.js version must be 18 or higher. Current: $(node -v)"
+    exit 1
+fi
+echo "✅ Node.js $(node -v)"
+
+# Check pnpm
+if ! command -v pnpm &> /dev/null; then
+    echo "❌ pnpm is not installed. Installing pnpm..."
+    npm install -g pnpm@10.11.0
+fi
+echo "✅ pnpm $(pnpm -v)"
+
+# Check Docker
+if ! command -v docker &> /dev/null; then
+    echo "❌ Docker is not installed. Please install Docker first."
+    echo "   Visit: https://docs.docker.com/get-docker/"
+    exit 1
+fi
+
+if ! docker info &> /dev/null; then
+    echo "❌ Docker daemon is not running. Please start Docker."
+    exit 1
+fi
+echo "✅ Docker is running"
+
+# Install dependencies
+echo ""
+echo "📦 Installing dependencies..."
+pnpm install
+
+# Set up Echo Control environment
+echo ""
+echo "🔧 Setting up Echo Control..."
+cd packages/app/control
+
+# Create .env from example if it doesn't exist
+if [ ! -f .env ]; then
+    cp .env.example .env
+    echo "✅ Created .env file from example"
+fi
+
+# Generate AUTH_SECRET if not exists
+if ! grep -q "^AUTH_SECRET=." .env; then
+    cd ../../..
+    pnpm local-setup
+    cd packages/app/control
+fi
+
+# Start PostgreSQL
+echo ""
+echo "🐘 Starting PostgreSQL database..."
+docker compose -f docker-local-db.yml up -d
+
+# Wait for PostgreSQL to be ready
+echo "⏳ Waiting for database to be ready..."
+RETRIES=30
+until docker compose -f docker-local-db.yml exec -T postgres pg_isready -U echo_user -d echo_control_v2 &> /dev/null || [ $RETRIES -eq 0 ]; do
+    echo -n "."
+    sleep 1
+    RETRIES=$((RETRIES-1))
+done
+echo ""
+
+if [ $RETRIES -eq 0 ]; then
+    echo "❌ Database failed to start. Check Docker logs:"
+    echo "   docker compose -f docker-local-db.yml logs"
+    exit 1
+fi
+
+echo "✅ PostgreSQL is ready"
+
+# Run database setup
+echo ""
+echo "🔄 Setting up database schema..."
+npx prisma generate
+npx prisma db push
+
+# Set up Echo Server environment
+echo ""
+echo "🔧 Setting up Echo Server..."
+cd ../server
+
+# Create .env if it doesn't exist
+if [ ! -f .env ]; then
+    cat > .env << 'EOF'
+# Database (uses same PostgreSQL as control)
+DATABASE_URL="postgresql://echo_user:echo_password@localhost:5469/echo_control_v2?schema=public"
+
+# Server Configuration
+PORT=3069
+NODE_ENV=development
+
+# API Keys (optional for local development)
+OPENAI_API_KEY=""
+ANTHROPIC_API_KEY=""
+GEMINI_API_KEY=""
+EOF
+    echo "✅ Created Echo Server .env file"
+fi
+
+# Success message
+echo ""
+echo "🎉 Setup complete!"
+echo ""
+echo "To start Echo:"
+echo "  cd ../../.."
+echo "  pnpm dev"
+echo ""
+echo "Then visit:"
+echo "  - Echo Dashboard: http://localhost:3000"
+echo "  - Echo Server: http://localhost:3069"
+echo ""
+echo "For local development, use the 'Local User' auth provider on the login page."

From 0ba1c8f591f9da8cc452a3758ff3c937f5b9b955 Mon Sep 17 00:00:00 2001
From: naaa760 <neh6a683@gmail.com>
Date: Fri, 14 Nov 2025 10:15:29 +0530
Subject: [PATCH 3/6] docs: simplify local development

---
 README.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 54d3f0c7b..96d91320e 100644
--- a/README.md
+++ b/README.md
@@ -119,9 +119,15 @@ Or run `npx echo-start my-app` to choose interactively.
 
 **Note:** The CLI template (`echo-cli`) requires manual installation from the repository as it's a command-line tool rather than a web application. See the [templates README](./templates/README.md) for details.
 
-# Development
+## Local Development
 
-Fill out `packages/app/control/.env` and `packages/app/server/.env`. Then...
+**Quick Start:**
 
-- `pnpm i`
-- `pnpm dev`
+```bash
+git clone https://github.com/Merit-Systems/echo.git
+cd echo
+pnpm setup    # Automated setup (requires Docker)
+pnpm dev      # Start servers
+```
+
+Visit http://localhost:3000. For manual setup or troubleshooting, see [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md).

From 7cb9ca0e89920ecb2ecbc1867af1513c76e88508 Mon Sep 17 00:00:00 2001
From: naaa760 <neh6a683@gmail.com>
Date: Fri, 14 Nov 2025 10:16:12 +0530
Subject: [PATCH 4/6] docs: update control README with Docker requirements and
 setup

---
 packages/app/control/README.md | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/packages/app/control/README.md b/packages/app/control/README.md
index 99d3dce93..105011cb8 100644
--- a/packages/app/control/README.md
+++ b/packages/app/control/README.md
@@ -46,15 +46,15 @@ A comprehensive Next.js application for managing Echo applications, API keys, an
 ### Prerequisites
 
 - Node.js 18+
-- PostgreSQL database
-- pnpm
+- Docker and Docker Compose (for PostgreSQL)
+- pnpm 10+
 
 ### Installation
 
 1. **Clone and navigate to the project**:
 
    ```bash
-   cd echo-control
+   cd packages/app/control
    ```
 
 2. **Install dependencies**:
@@ -63,28 +63,42 @@ A comprehensive Next.js application for managing Echo applications, API keys, an
    pnpm install
    ```
 
-3. **Create .env file**:
+3. **Set up environment**:
 
    ```bash
-   # Generate .env file
+   # Copy example env file
+   cp .env.example .env
+   
+   # Generate AUTH_SECRET
+   cd ../../..
    pnpm local-setup
+   cd packages/app/control
    ```
 
-4. **Run database migrations**:
+4. **Start PostgreSQL with Docker**:
+
+   ```bash
+   # Make sure Docker is running first!
+   docker compose -f docker-local-db.yml up -d
+   ```
+
+5. **Set up database**:
 
    ```bash
    npx prisma generate
    npx prisma db push
    ```
 
-5. **Start the development server**:
+6. **Start the development server**:
 
    ```bash
-   pnpm run dev
+   pnpm dev
    ```
 
-6. **Open the application**:
+7. **Open the application**:
    Visit [http://localhost:3000](http://localhost:3000)
+   
+   In development mode, use the "Local User" authentication provider for quick access.
 
 ## Features Overview
 

From 249ad80321a8768107f4fd98a4d0e486180f25ec Mon Sep 17 00:00:00 2001
From: naaa760 <neh6a683@gmail.com>
Date: Fri, 14 Nov 2025 10:16:46 +0530
Subject: [PATCH 5/6] feat: add setup script command to package.json

---
 package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/package.json b/package.json
index 48b012f52..f5d5894ea 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
   "scripts": {
     "dev": "turbo run dev --filter=echo-control --filter=echo-server",
     "local-setup": "turbo run local-setup --filter=echo-control",
+    "setup": "./scripts/setup-local.sh",
     "build": "turbo run build --env-mode=loose",
     "prepare": "SKIP_ENV_VALIDATION=true turbo run build --env-mode=loose --filter=./packages/sdk/* --filter=!echo-next-example --filter=!echo-vite-example --filter=!registry",
     "test:unit": "pnpm -C packages/sdk/ts run build && pnpm -r --filter=!packages/app/server run test:unit",

From 309705e65f7a056281a76892c34d54542a4d46ff Mon Sep 17 00:00:00 2001
From: naaa760 <neh6a683@gmail.com>
Date: Fri, 14 Nov 2025 10:20:25 +0530
Subject: [PATCH 6/6] update

---
 scripts/setup-local.sh | 60 +++++++++++++++---------------------------
 1 file changed, 21 insertions(+), 39 deletions(-)

diff --git a/scripts/setup-local.sh b/scripts/setup-local.sh
index 647d6973d..1020816de 100755
--- a/scripts/setup-local.sh
+++ b/scripts/setup-local.sh
@@ -1,77 +1,66 @@
 #!/bin/bash
-# setup-local.sh - Automated local development setup for Echo
 
 set -e
 
-echo "🚀 Setting up Echo for local development..."
+echo "Setting up Echo for local development..."
 
-# Check prerequisites
-echo "📋 Checking prerequisites..."
+echo "Checking prerequisites..."
 
-# Check Node.js
 if ! command -v node &> /dev/null; then
-    echo "❌ Node.js is not installed. Please install Node.js 18+ first."
+    echo "Node.js is not installed. Please install Node.js 18+ first."
     echo "   Visit: https://nodejs.org/"
     exit 1
 fi
 
 NODE_VERSION=$(node -v | cut -d'.' -f1 | sed 's/v//')
 if [ "$NODE_VERSION" -lt 18 ]; then
-    echo "❌ Node.js version must be 18 or higher. Current: $(node -v)"
+    echo "Node.js version must be 18 or higher. Current: $(node -v)"
     exit 1
 fi
-echo "✅ Node.js $(node -v)"
+echo "Node.js $(node -v)"
 
-# Check pnpm
 if ! command -v pnpm &> /dev/null; then
-    echo "❌ pnpm is not installed. Installing pnpm..."
+    echo "pnpm is not installed. Installing pnpm..."
     npm install -g pnpm@10.11.0
 fi
-echo "✅ pnpm $(pnpm -v)"
+echo "pnpm $(pnpm -v)"
 
-# Check Docker
 if ! command -v docker &> /dev/null; then
-    echo "❌ Docker is not installed. Please install Docker first."
+    echo "Docker is not installed. Please install Docker first."
     echo "   Visit: https://docs.docker.com/get-docker/"
     exit 1
 fi
 
 if ! docker info &> /dev/null; then
-    echo "❌ Docker daemon is not running. Please start Docker."
+    echo "Docker daemon is not running. Please start Docker."
     exit 1
 fi
-echo "✅ Docker is running"
+echo "Docker is running"
 
-# Install dependencies
 echo ""
-echo "📦 Installing dependencies..."
+echo "Installing dependencies..."
 pnpm install
 
-# Set up Echo Control environment
 echo ""
-echo "🔧 Setting up Echo Control..."
+echo "Setting up Echo Control..."
 cd packages/app/control
 
-# Create .env from example if it doesn't exist
 if [ ! -f .env ]; then
     cp .env.example .env
-    echo "✅ Created .env file from example"
+    echo "Created .env file from example"
 fi
 
-# Generate AUTH_SECRET if not exists
 if ! grep -q "^AUTH_SECRET=." .env; then
     cd ../../..
     pnpm local-setup
     cd packages/app/control
 fi
 
-# Start PostgreSQL
 echo ""
-echo "🐘 Starting PostgreSQL database..."
+echo "Starting PostgreSQL database..."
 docker compose -f docker-local-db.yml up -d
 
-# Wait for PostgreSQL to be ready
-echo "⏳ Waiting for database to be ready..."
+echo "Waiting for database to be ready..."
 RETRIES=30
 until docker compose -f docker-local-db.yml exec -T postgres pg_isready -U echo_user -d echo_control_v2 &> /dev/null || [ $RETRIES -eq 0 ]; do
     echo -n "."
@@ -81,45 +70,38 @@ done
 echo ""
 
 if [ $RETRIES -eq 0 ]; then
-    echo "❌ Database failed to start. Check Docker logs:"
+    echo "Database failed to start. Check Docker logs:"
     echo "   docker compose -f docker-local-db.yml logs"
     exit 1
 fi
 
-echo "✅ PostgreSQL is ready"
+echo "PostgreSQL is ready"
 
-# Run database setup
 echo ""
-echo "🔄 Setting up database schema..."
+echo "Setting up database schema..."
 npx prisma generate
 npx prisma db push
 
-# Set up Echo Server environment
 echo ""
-echo "🔧 Setting up Echo Server..."
+echo "Setting up Echo Server..."
 cd ../server
 
-# Create .env if it doesn't exist
 if [ ! -f .env ]; then
     cat > .env << 'EOF'
-# Database (uses same PostgreSQL as control)
 DATABASE_URL="postgresql://echo_user:echo_password@localhost:5469/echo_control_v2?schema=public"
 
-# Server Configuration
 PORT=3069
 NODE_ENV=development
 
-# API Keys (optional for local development)
 OPENAI_API_KEY=""
 ANTHROPIC_API_KEY=""
 GEMINI_API_KEY=""
 EOF
-    echo "✅ Created Echo Server .env file"
+    echo "Created Echo Server .env file"
 fi
 
-# Success message
 echo ""
-echo "🎉 Setup complete!"
+echo "Setup complete!"
 echo ""
 echo "To start Echo:"
 echo "  cd ../../.."