# How to Set Up the Kaneo Web Application Locally: Complete Development Guide

> Set up the Kaneo web application locally with this guide. Clone the usekaneo kaneo repo, install pnpm dependencies, configure env variables, and run pnpm dev to start.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-09

---

**To set up the Kaneo web application locally, clone the usekaneo/kaneo repository, install dependencies with pnpm, configure environment variables in a root `.env` file, and run `pnpm dev` to start the API and web development servers.**

Setting up the Kaneo web front-end for local development follows a reproducible workflow that leverages the monorepo’s shared environment configuration and TurboRepo build system. The process requires configuring a PostgreSQL database and environment variables before launching the concurrent development servers.

## Prerequisites

Before you begin, ensure your system meets the following requirements:

- **pnpm 10.x** as the package manager (the repository does not support npm or yarn)
- **Node.js** (version compatible with the workspace engines defined in [`apps/web/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/web/package.json) and [`apps/api/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/api/package.json))
- **PostgreSQL** (either a local instance or Docker to run the containerized database)

## Step 1: Clone the Repository and Install Dependencies

Start by cloning the Kaneo monorepo and installing all workspace dependencies from the root directory.

```bash
git clone https://github.com/usekaneo/kaneo.git
cd kaneo
pnpm install

```

The `pnpm install` command installs dependencies for both the API and web workspaces defined in [`apps/api/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/api/package.json) and [`apps/web/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/web/package.json), respectively.

## Step 2: Configure Environment Variables

Kaneo stores all required configuration in a single `.env` file at the repository root. Copy the sample file and populate the required variables:

```bash
cp .env.sample .env

```

Edit `.env` to include at minimum these values:

```dotenv
KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=<32-character-random-hex-string>
DATABASE_URL=postgresql://kaneo:kaneo@localhost:5432/kaneo
POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=<your-secure-password>

```

For a complete list of variables and their descriptions, refer to **[ENVIRONMENT_SETUP.md](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)** in the repository root.

## Step 3: Set Up PostgreSQL

If you do not have a local PostgreSQL server running, use the provided Docker Compose configuration to spin up an isolated database instance.

Create a [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) file with the following content (as documented in the README):

```yaml
services:
  postgres:
    image: postgres:16-alpine
    env_file:
      - .env
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kaneo -d kaneo"]
      interval: 10s
      timeout: 5s
      retries: 5

  kaneo:
    image: ghcr.io/usekaneo/kaneo:latest
    ports:
      - "5173:5173"
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres_data:

```

Launch the services:

```bash
docker compose -f compose.yml up -d

```

Alternatively, if using an existing PostgreSQL instance, ensure the `DATABASE_URL` in your `.env` file points to your active server.

## Step 4: Start the Development Servers

With the database running and environment configured, start both the API and web servers in watch mode using the root-level development script:

```bash
pnpm dev

```

This command triggers TurboRepo to concurrently launch:
- The **API server** on port **1337** (defined in [`apps/api/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/api/package.json))
- The **web application** on port **5173** (defined in [`apps/web/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/web/package.json))

Both services reload automatically when you modify source code.

## Step 5: Access the Web Interface

Navigate to `http://localhost:5173` in your browser. The React front-end (powered by Vite as configured in [`apps/web/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/web/package.json)) automatically connects to the API at `http://localhost:1337`.

If you encounter CORS errors, verify that `KANEO_CLIENT_URL` and `KANEO_API_URL` match your actual localhost URLs. You may also set `CORS_ORIGINS` in `.env` explicitly as documented in **[ENVIRONMENT_SETUP.md](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)**.

## Summary

- Clone the **usekaneo/kaneo** repository and run `pnpm install` at the root to install monorepo dependencies.
- Copy `.env.sample` to `.env` and configure `KANEO_CLIENT_URL`, `KANEO_API_URL`, `AUTH_SECRET`, and `DATABASE_URL` before starting servers.
- Use the provided [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) to run PostgreSQL via Docker Compose, or connect to an existing database instance.
- Execute `pnpm dev` to start both the API (port 1337) and web application (port 5173) with hot-reload enabled.
- Consult [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) for troubleshooting CORS issues and customizing Vite environment variables in `apps/web/.env.example`.

## Frequently Asked Questions

### What package manager does Kaneo require?

Kaneo requires **pnpm 10.x** and will not install correctly with npm or yarn. The monorepo uses pnpm workspaces to manage dependencies across [`apps/web/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/web/package.json) and [`apps/api/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/api/package.json) from the repository root.

### How do I troubleshoot CORS errors when running Kaneo locally?

CORS errors typically occur when `KANEO_CLIENT_URL` and `KANEO_API_URL` in your `.env` file do not match the actual URLs you are using in the browser. Ensure both variables are set correctly (e.g., `http://localhost:5173` and `http://localhost:1337`), and optionally define `CORS_ORIGINS` explicitly as documented in **ENVIRONMENT_SETUP.md**.

### Can I run Kaneo without Docker?

Yes. While the [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) file provides a convenient PostgreSQL container, you can run Kaneo locally by pointing `DATABASE_URL` in your `.env` file to any accessible PostgreSQL server. You only need Docker if you want the containerized database setup described in the quick-start guide.

### What ports does the Kaneo web application use?

By default, the Kaneo web application runs on **port 5173** (Vite dev server) and the API runs on **port 1337**. These are configured via `KANEO_CLIENT_URL` and `KANEO_API_URL` environment variables, and can be overridden if those ports are already occupied on your system.