Skip to main content

​
Prerequisites

Before starting, ensure you have the following installed:
  • Node.js v20 or higher
  • PostgreSQL with pgvector extension enabled
  • Redis Server (local or remote)
  • Git

​
Environment Setup

1
Clone the Repository
2
git clone <repository-url>
cd kaiu-natural-living
3
Install Dependencies
4
npm install
5
Configure Environment Variables
6
Create environment files from examples:
7
cp .env.example .env.local
cp .env.example prisma/.env
8
Update the following critical variables:
9
Database Configuration
10
DATABASE_URL="postgresql://user:password@localhost:5432/kaiu_db"
11
Redis Configuration
12
REDIS_HOST="localhost"
REDIS_PORT="6379"
13
WhatsApp Cloud API
14
WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"
WHATSAPP_TOKEN="your_access_token"
WHATSAPP_VERIFY_TOKEN="your_verify_token"
15
AI Configuration
16
ANTHROPIC_API_KEY="your_anthropic_key"
17
Setup Database
18
Push the Prisma schema to your database:
19
npx prisma db push
20
Optionally, seed initial data:
21
npm run seed
22
See the Seeding Guide for details on what data gets seeded.
23
Start Development Servers
24
Use the magic script to start everything:
25
./START_ALL.sh
26
This script will:
27
  • Start Redis server (if not running)
  • Launch the backend API on port 3001
  • Launch the Vite frontend on port 8080

    • ​
    Manual Start (Alternative)

    If you prefer to start services individually:

    ​
    Start Redis

    redis-server --daemonize yes

    ​
    Start Backend API

    npm run api:dev
    The backend will run on http://localhost:3001 with hot reload via nodemon.

    ​
    Start Frontend

    npm run dev
    The frontend will run on http://localhost:8080 with HMR enabled.

    ​
    Available NPM Scripts

    ​
    Frontend Development

    • npm run dev - Start Vite dev server (port 8080)
    • npm run build - Production build
    • npm run build:dev - Development build
    • npm run preview - Preview production build

    ​
    Backend Development

    • npm run api - Start backend server
    • npm run api:dev - Start backend with nodemon (hot reload)

    ​
    Testing

    • npm run test - Run all tests once
    • npm run test:watch - Run tests in watch mode

    ​
    Code Quality

    • npm run lint - Run ESLint

    ​
    Verifying the Setup

    1
    Check Redis Connection
    2
    redis-cli ping
    3
    Should return: PONG
    4
    Check Database Connection
    5
    npx prisma studio
    6
    Opens Prisma Studio at http://localhost:5555 to browse your database.
    7
    Check API Health
    8
    Visit: http://localhost:3001/api/health (if health endpoint exists)
    9
    Check Frontend
    10
    Visit: http://localhost:8080

    ​
    Troubleshooting

    ​
    Redis Connection Issues

    If Redis fails to start: 
    # Check if Redis is already running
pgrep redis-server

# Start manually
sudo systemctl start redis
# OR
redis-server /path/to/redis.conf

    ​
    Database Connection Issues

    Ensure PostgreSQL is running and the pgvector extension is installed: 
    CREATE EXTENSION IF NOT EXISTS vector;

    ​
    Port Already in Use

    If port 3001 or 8080 is in use: 
    # Find process using the port
lsof -i :3001
lsof -i :8080

# Kill the process
kill -9 <PID>

    ​
    Next Steps

    Build docs developers (and LLMs) love

    Get started for freeTalk to us