> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Run KaireonAI on your local machine for licensed development and evaluation.

<Note>
  Running KaireonAI yourself is an **Enterprise offering under a commercial license**. Source and image access is provisioned as part of an Enterprise agreement — this is not a free or open download. [Contact sales](mailto:sales@kaireonai.com). To evaluate the platform at no cost, use the hosted [Playground](https://playground.kaireonai.com/register).
</Note>

## Prerequisites

| Dependency | Version | Required           |
| ---------- | ------- | ------------------ |
| Node.js    | 22+     | Yes                |
| PostgreSQL | 14+     | Yes                |
| Python     | 3.11+   | No (for ML Worker) |
| Redis      | 6+      | No (recommended)   |

### Install PostgreSQL

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    brew install postgresql@16
    brew services start postgresql@16
    createdb kaireon
    ```
  </Tab>

  <Tab title="Ubuntu/Debian">
    ```bash theme={null}
    sudo apt install postgresql postgresql-contrib
    sudo systemctl start postgresql
    sudo -u postgres createdb kaireon
    ```
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    docker run -d --name kaireon-pg \
      -e POSTGRES_DB=kaireon \
      -e POSTGRES_USER=postgres \
      -e POSTGRES_PASSWORD=postgres \
      -p 5432:5432 \
      postgres:16
    ```
  </Tab>
</Tabs>

### Install Redis (Optional)

KaireonAI uses Redis for enrichment data caching and API rate limiting. Without it, the platform runs fine but skips these features.

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    brew install redis
    brew services start redis
    ```
  </Tab>

  <Tab title="Ubuntu/Debian">
    ```bash theme={null}
    sudo apt install redis-server
    sudo systemctl start redis-server
    ```
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    docker run -d --name kaireon-redis -p 6379:6379 redis:7-alpine
    ```
  </Tab>
</Tabs>

## Platform Setup

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone https://github.com/kaireonai/platform.git
    cd platform
    npm install
    ```
  </Step>

  <Step title="Create .env file">
    ```bash theme={null}
    cp .env.example .env
    ```

    Edit `.env`:

    ```env theme={null}
    DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kaireon
    REDIS_URL=redis://localhost:6379
    NEXTAUTH_SECRET=local-dev-secret-change-in-production
    ```
  </Step>

  <Step title="Initialize the database">
    ```bash theme={null}
    npx prisma generate
    npx prisma db push
    npx tsx prisma/seed.ts
    ```

    The seed script creates the default tenant and an admin user:

    * Email: `admin@kaireonai.com`
    * Password: `admin123`

    <Warning>
      `prisma db push` is safe **only on a fresh database**. On a populated database it drops any table not defined in `schema.prisma` — including the runtime-created `ds_*` customer-schema tables and `_flow_*` pipeline staging tables — which means data loss. Once you have real data, evolve the schema with the numbered files in `prisma/manual-sql/` applied via `psql`, not `db push`.
    </Warning>
  </Step>

  <Step title="Start the development server">
    ```bash theme={null}
    npm run dev
    ```

    Open [http://localhost:3000](http://localhost:3000) and sign in with the admin credentials.
  </Step>
</Steps>

## ML Worker Setup (Optional)

The ML Worker provides scikit-learn-based analysis for AI features. It's optional — all AI features fall back to LLM-based analysis without it.

<Steps>
  <Step title="Set up environment">
    ```bash theme={null}
    cd ml-worker
    cp .env.example .env
    ```

    Edit `ml-worker/.env` to match your local database:

    ```env theme={null}
    DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kaireon
    ```
  </Step>

  <Step title="Install Python dependencies">
    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Start the ML Worker">
    ```bash theme={null}
    python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
    ```
  </Step>

  <Step title="Connect the platform">
    Add to `platform/.env`:

    ```env theme={null}
    ML_WORKER_URL=http://localhost:8000
    ```

    Restart the Next.js dev server. The **AI > Insights** page should show "ML Worker Connected".
  </Step>
</Steps>

## Docker Compose (Full Stack)

Run the entire stack with Docker Compose instead of installing each dependency. The `docker-compose.yml` lives at the **repository root**:

```bash theme={null}
cp .env.example .env   # set POSTGRES_PASSWORD and NEXTAUTH_SECRET at minimum

# Platform only
docker compose up -d

# Platform + ML Worker (ml profile)
docker compose --profile ml up -d
```

This starts PostgreSQL, PgBouncer, Redis, the API, the background worker, and optionally the ML Worker, with the app served on [http://localhost:3000](http://localhost:3000). The API entrypoint waits for the database, runs `npx prisma db push --skip-generate` to sync the schema, then starts the server.

<Warning>
  The Compose `api` and `worker` services run with `NODE_ENV=production`, so the platform's startup validation **requires** a full set of production security secrets. The shipped `docker-compose.yml` now provides working **dev-only defaults** for all of them (via `${VAR:-default}` substitutions in a shared `x-app-secrets` block), so `docker compose up` starts cleanly with no configuration.

  The required variables are `NEXTAUTH_SECRET`, `JWT_SIGNING_SECRET`, `CONNECTOR_ENCRYPTION_KEY`, `WEBHOOK_SIGNING_SECRET`, `API_KEY_PEPPER`, and a non-wildcard `CORS_ALLOWED_ORIGINS`. The baked-in defaults are **not secret** — anyone can read them in the repo — so before exposing the stack to anyone else, override each one (plus `POSTGRES_PASSWORD`). Because they use `${VAR:-...}` substitution, Compose interpolates any value you export in your shell or set in `.env`, so you no longer need to edit the Compose file:

  ```env theme={null}
  # .env — overrides the dev-only defaults baked into docker-compose.yml
  POSTGRES_PASSWORD=...
  NEXTAUTH_SECRET=...
  JWT_SIGNING_SECRET=...
  CONNECTOR_ENCRYPTION_KEY=...
  WEBHOOK_SIGNING_SECRET=...
  API_KEY_PEPPER=...
  CORS_ALLOWED_ORIGINS=https://your-app.example.com
  ```

  `CORS_ALLOWED_ORIGINS` must be set and must not be `*`. Generate strong secrets with `openssl rand -hex 32`. See the [environment variable reference](/self-host/deploy/options#environment-variables) for details.
</Warning>

<Info>
  The ML Worker includes a health check (`/health` on port 8000) that Docker runs on a schedule. Check its reported status — `healthy`, `unhealthy`, or `starting` — with `docker compose ps`.
</Info>

## Verify Installation

After signing in, check the home dashboard — you should see cards for Decision Flows, Offers, Channels, etc. all at zero counts.

To load demo content, go to **Settings → Sample Data** and load the **Retail Rewards** dataset. This will populate the platform with schemas, offers, channels, models, and creatives.

## Running Tests

```bash theme={null}
npm test              # Run tests in watch mode
npm run test:coverage # Run with coverage report
npm run build         # Type-check + production build
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Prisma 7: 'The datasource property url is no longer supported'">
    Prisma 7 moved the connection URL out of `schema.prisma` and into `prisma.config.ts`. If you see this error, remove the `url = env("DATABASE_URL")` line from `prisma/schema.prisma`. The datasource block should only contain `provider = "postgresql"`. The connection URL is configured in `prisma.config.ts`.
  </Accordion>

  <Accordion title="Port 3000 already in use">
    Another process is using port 3000. Find and stop it:

    ```bash theme={null}
    lsof -ti:3000 | xargs kill -9
    npm run dev
    ```

    Alternatively, start on a different port:

    ```bash theme={null}
    PORT=3001 npm run dev
    ```
  </Accordion>

  <Accordion title="Redis connection refused (optional dependency)">
    Redis is optional for local development. If Redis is not running, the platform skips enrichment caching, rate limiting, and circuit breaker features but otherwise works normally. To suppress connection warnings, remove `REDIS_URL` from your `.env` file. To install Redis, see the [Install Redis](#install-redis-optional) section above.
  </Accordion>

  <Accordion title="npx prisma generate fails with 'Cannot find module'">
    Ensure you are running commands from the `platform/` directory (not the repo root). The Prisma 7 config expects `prisma.config.ts` in the working directory:

    ```bash theme={null}
    cd platform
    npx prisma generate
    ```
  </Accordion>

  <Accordion title="NEXTAUTH_SECRET warning in development">
    The platform warns if `NEXTAUTH_SECRET` is not set in development. Auth features (login, session management) will not work correctly without it. Add any random string to your `.env`:

    ```env theme={null}
    NEXTAUTH_SECRET=local-dev-secret-change-in-production
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Platform Walkthrough" icon="play" href="/get-started/walkthrough">
    Build a complete decisioning setup step by step.
  </Card>

  <Card title="Cloud Deployment" icon="cloud" href="/self-host/deploy/cloud">
    Ready for production? Deploy to AWS App Runner.
  </Card>

  <Card title="Kubernetes" icon="dharmachakra" href="/self-host/deploy/kubernetes">
    Deploy to any Kubernetes cluster using the Helm chart.
  </Card>

  <Card title="ML Worker" icon="microchip" href="/self-host/deploy/ml-worker">
    Add the Python ML Worker for AI-powered analysis.
  </Card>
</CardGroup>