Skip to main content

Setup Guide for First-Time Users

This guide covers the complete setup process for running AllMyChats locally. Follow these steps in order to get the project running on your machine.

Prerequisites​

Before starting, ensure you have installed:

Step 1: Clone Repository & Install Dependencies​

# Clone the repository
git clone <your-repo-url>
cd whatsapp-message-AI-analysis-agent

# Install all dependencies
npm install

Warning: Do NOT skip npm install. This is required for all development tools and dependencies.

Step 2: Environment Configuration​

Create .env File​

  1. Copy the environment template:

    cp .env.example .env

  2. Open .env in your editor and fill in the required values below.

⚠️ CRITICAL WARNING: Never commit .env to version control. It contains sensitive credentials. Ensure .env is in .gitignore.

Required Environment Variables​

Database Configuration​

NODE_ENV=development
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/AllMyChats_ai"
  • Leave DATABASE_URL as-is for local development (Docker will provide the database)
  • Change the database password in production

Authentication (Better Auth)​

BETTER_AUTH_SECRET="your-secret-key-here"
VITE_BETTER_AUTH_URL="http://localhost:3000"

  • Generate a secure secret key for production:

    # On macOS/Linux
    openssl rand -base64 32

    # On Windows (PowerShell)
    [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes([System.Guid]::NewGuid().ToString()))

Google OAuth (Optional)​

GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

Stripe Payment Integration​

STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
VITE_STRIPE_BASIC_PRICE_ID="price_..."
VITE_STRIPE_PRO_PRICE_ID="price_..."
VITE_STRIPE_PUBLISHABLE_KEY="pk_test_..."
  • Get keys from: https://dashboard.stripe.com/apikeys
  • Create products/prices in Stripe Dashboard and copy their IDs
  • Leave empty to disable Stripe for development (feature access will be limited)

Cloud Storage (R2/S3)​

R2_ACCESS_KEY_ID=""
R2_SECRET_ACCESS_KEY=""
VITE_R2_BUCKET=""
VITE_R2_ENDPOINT=""
  • Get credentials from: https://dash.cloudflare.com/ (R2 section)
  • Leave empty to disable file uploads (features requiring uploads will be unavailable)

Anthropic Claude API​

ANTHROPIC_API_KEY=""

Twilio Messaging Integration​

TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
TWILIO_AUTH_TOKEN="your-auth-token-here"
TWILIO_WEBHOOK_SECRET="your-webhook-secret-here"
  • Get credentials from: https://www.twilio.com/console
  • Account SID and Auth Token are on the main console page
  • Leave empty to disable real-time message sync

Step 3: Database Setup​

Start PostgreSQL Database​

npm run db:up

This starts a PostgreSQL container using Docker Compose. The database will be accessible at:

  • Host: localhost
  • Port: 5432
  • Username: postgres
  • Password: postgres
  • Database: AllMyChats_ai

Warning: The default credentials above are for development only. Change them in production.

Run Database Migrations​

npm run db:migrate

This creates all necessary tables and schema.

(Optional) Seed Database​

npm run db:seed

This populates the database with sample data for testing.

(Optional) Clear Database​

npm run db:seed:clear

This removes all seeded data.

Database Studio (Optional)​

View and manage your database graphically:

npm run db:studio

Opens Drizzle Studio at http://localhost:5555

Step 4: Stripe Webhook Setup (Optional)​

If using Stripe, listen for webhooks during development:

npm run stripe:listen

This forwards Stripe webhook events to your local server at localhost:3000/api/stripe/webhook.

Step 5: Start Development Server​

npm run dev

The application will be available at: http://localhost:3000

Note: First startup may take a minute as it compiles TypeScript and builds assets.

Step 6: (Optional) Type Check & Linting​

Before committing code, run:

# Check TypeScript types
npm run type-check

# Run linter
npm run lint

# Fix linting errors automatically
npm run lint:fix

# Format code
npm run format

# Run all checks
npm run lint:all

Common Commands Reference​

CommandPurpose
npm run devStart development server (port 3000)
npm run buildBuild for production with type checking
npm run startStart production server
npm run db:upStart PostgreSQL container
npm run db:downStop PostgreSQL container
npm run db:migrateRun pending migrations
npm run db:generateGenerate new migration files
npm run db:seedSeed database with sample data
npm run db:studioOpen Drizzle Studio (database UI)
npm run stripe:listenListen for Stripe webhooks
npm run lint:allType check, lint, and format check
npm run testRun end-to-end tests
npm run test:uiRun tests with UI dashboard

Troubleshooting​

Port 3000 Already in Use​

If port 3000 is already occupied:

# Find process using port 3000 and kill it
# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows (PowerShell, as Admin)
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force

Docker Issues​

# Stop all Docker containers
docker compose down

# Restart from scratch
npm run db:down
npm run db:up
npm run db:migrate

Database Connection Error​

  • Verify DATABASE_URL in .env matches your PostgreSQL credentials
  • Ensure Docker container is running: docker compose ps
  • Check PostgreSQL logs: docker compose logs postgres

Missing Dependencies​

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

TypeScript Errors​

# Run type checker to see all errors
npm run type-check

# Build will also catch these errors
npm run build

Port 5432 (Database) Already in Use​

# Find and kill the process using port 5432
# macOS/Linux
lsof -ti:5432 | xargs kill -9

# Windows (PowerShell, as Admin)
Get-Process -Id (Get-NetTCPConnection -LocalPort 5432).OwningProcess | Stop-Process -Force

# Then restart the database
npm run db:down
npm run db:up
npm run db:migrate

Quick Start Checklist​

  • Node.js v18+ installed
  • Docker & Docker Compose installed
  • Repository cloned
  • npm install completed
  • .env file created and configured with at least database credentials
  • npm run db:up - database running
  • npm run db:migrate - migrations applied
  • npm run dev - development server started
  • Application accessible at http://localhost:3000

Need Help?​

  • Check developer documentation for detailed technical documentation
  • Review Architecture Guide for architecture overview
  • Check your environment variables are correct
  • Verify all prerequisites are installed
  • Review error messages in console output