# How to Build the Kaneo Project from Source: A Complete Developer Guide

> Learn to build the Kaneo project from source with this developer guide. Clone the repo, install dependencies, configure .env, and run pnpm dev to start the API and web client.

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

---

**To build Kaneo from source, clone the repository, run `pnpm install` to install the monorepo dependencies, configure your `.env` file with database and authentication secrets, and execute `pnpm dev` to start the API and web client simultaneously.**

Kaneo is an open-source project management platform structured as a **pnpm monorepo**. Whether you're contributing features or self-hosting a custom instance, learning how to build the Kaneo project from source gives you full control over the runtime environment and database configuration.

## Prerequisites and Monorepo Structure

Before building, ensure you have **Node.js** (v20 or later), **pnpm**, and a running **PostgreSQL** instance available on your system. The repository organizes code into three distinct runtime components managed by **TurboRepo**:

| Component | Path | Technology Stack |
|-----------|------|------------------|
| **API Server** | `apps/api/` | Hono framework with Drizzle ORM and Better Auth |
| **Web Client** | `apps/web/` | React 19, Vite, and TanStack Query |
| **Documentation** | `apps/docs/` | Next.js static site generator |

The root [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) defines the workspace glob patterns (`apps/*`, `packages/*`), enabling pnpm to hoist shared dependencies and link internal packages correctly.

## Step 1: Clone and Install Dependencies

Begin by cloning the repository and installing all workspace dependencies with pnpm. This command resolves packages across the entire monorepo, including shared utilities in the `packages/` directory.

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

```

The installation process reads [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) to identify all sub-packages and establishes the internal dependency graph required for TurboRepo orchestration.

## Step 2: Configure Environment Variables

Kaneo requires several environment variables to connect the API server to your PostgreSQL database and secure user authentication sessions. Copy the sample configuration file and customize the values for your local environment:

```bash
cp .env.sample .env

```

Edit the `.env` file to include at minimum these three values:

- `KANEO_CLIENT_URL=http://localhost:5173` — The origin where the web client runs
- `POSTGRES_PASSWORD=your-secure-password` — Credentials for your PostgreSQL instance
- `AUTH_SECRET=$(openssl rand -hex 32)` — A random 32-byte hex string for Better Auth encryption

The API server reads these variables at runtime via `process.env` in [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts). For a complete list of optional configuration parameters, consult [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) in the repository root.

## Step 3: Start the Development Servers

With dependencies installed and environment variables set, you can launch the development stack. The root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) provides convenience scripts that leverage TurboRepo to run services in parallel with hot-reload.

### Run the Full Stack

To start both the API server and web client simultaneously in watch mode:

```bash
pnpm dev

```

This command executes the `dev` pipeline defined in [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json), launching `@kaneo/api` on port **1337** and `@kaneo/web` on port **5173**. Access the UI at `http://localhost:5173`.

### Run Individual Services

For targeted debugging or when working on only one component, use pnpm's filter flag to start services in isolation:

```bash

# API server only (Hono backend)

pnpm --filter @kaneo/api dev

# Web client only (Vite/React frontend)

pnpm --filter @kaneo/web dev

```

## Working with the Source Code

When extending Kaneo, you will interact with the database layer in the API and the data fetchers in the web client.

### Creating API Endpoints

The API uses Hono controllers with Drizzle ORM. Here is the pattern for inserting records, taken from [`apps/api/src/projects/controllers/create-project.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/projects/controllers/create-project.ts):

```typescript
import { db } from "@/database";
import { projectTable } from "@/database/schema";
import { createId } from "@paralleldrive/cuid2";

export async function createProject(name: string, userId: string) {
  const id = createId();
  await db
    .insert(projectTable)
    .values({ id, name, ownerId: userId })
    .run();
  return { id, name };
}

```

### Fetching Data in the Web Client

The frontend uses a centralized API client. This example from [`apps/web/src/fetchers/projects/get-project.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/fetchers/projects/get-project.ts) demonstrates type-safe data fetching:

```typescript
import { api } from "@/lib/api-client";

export async function getProject(id: string) {
  const res = await api.get(`/projects/${id}`);
  return res.json();
}

```

## Alternative Deployment Options

If you prefer containerized environments over local Node.js development, Kaneo provides several production-ready alternatives:

- **Docker Compose**: Save the [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) snippet from the README, configure your `.env` file, and run `docker compose up -d` to launch the entire stack including PostgreSQL.
- **Kubernetes**: Deploy using the Helm chart located in `charts/kaneo/`. Detailed values and installation steps are documented in [`charts/kaneo/README.md`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/README.md).
- **Drim CLI**: Execute the one-liner `curl -fsSL https://assets.kaneo.app/install.sh | sh && drim setup` for automated server provisioning on compatible cloud providers.

## Summary

Building Kaneo from source requires understanding its pnpm monorepo architecture. Key steps include:

- Cloning the repository and running `pnpm install` to resolve workspace dependencies defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml)
- Configuring the `.env` file with database credentials and an `AUTH_SECRET` for Better Auth
- Using `pnpm dev` to launch the full stack, or `pnpm --filter` commands to run individual services
- Accessing the development web client at `http://localhost:5173` and the API at `http://localhost:1337`

## Frequently Asked Questions

### What are the system requirements to build Kaneo from source?

You need Node.js version 20 or newer, pnpm (version 8 or later), and a PostgreSQL database (version 14+). The build process relies on TurboRepo to coordinate tasks across the monorepo, so pnpm is mandatory for workspace resolution.

### How do I run only the API server without the web client?

Use the pnpm filter command to target the specific workspace: `pnpm --filter @kaneo/api dev`. This starts the Hono server on port 1337 without launching the Vite development server for the frontend.

### Can I build Kaneo without installing Node.js locally?

Yes, you can use the Docker Compose setup documented in the README. This method containers the API, web client, and PostgreSQL database, eliminating the need for local pnpm or Node.js installation while still building the project from source code.

### Where are the database schema and migrations located?

The Drizzle ORM schema definitions reside in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts). Migration files are stored in `apps/api/src/database/migrations/` and are applied automatically when the API server starts in development mode, or manually via the `drizzle-kit` CLI.