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

> Learn to build the Kaneo project from source. This guide covers cloning the repo, installing dependencies, configuring .env, and running dev servers for API and web client. Start your Kaneo development today.

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

---

**To build Kaneo from source, clone the repository, install pnpm 10+, run `pnpm install` to resolve the monorepo dependencies, configure your `.env` file, and execute `pnpm dev` to start the development servers for the API and web client.**

Kaneo is an open-source project management platform organized as a **pnpm monorepo** containing the entire application stack. This guide explains how to build the Kaneo project from source using the repository at `usekaneo/kaneo`, covering local development setup, production builds, and containerized deployment options.

## Prerequisites

Before building Kaneo from source, ensure your environment meets these requirements:

- **Node.js** version 18 or higher
- **pnpm** version 10 or higher (`npm i -g pnpm@10`)
- **PostgreSQL** database server running locally or accessible via network

The build system relies on pnpm's workspace features to link internal packages, making the specific version critical for proper dependency resolution.

## Understanding the Monorepo Structure

Kaneo organizes code into a unified workspace defined in [[`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml)](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml). The repository structure separates concerns into distinct applications and shared packages:

- **`apps/api`** – Backend API built with **Hono**, using **PostgreSQL** via Drizzle ORM and **Better Auth** for authentication
- **`apps/web`** – Frontend application built with **React 19+**, **Vite**, **TanStack Router/Query**, and styled with **Tailwind v4**
- **`packages/*`** – Shared utilities, TypeScript configurations, and optional services (email, permissions)
- **`Dockerfile.kaneo`** and **`charts/kaneo`** – Container images and Helm charts for production deployments

Both the API and web client share a single `.env` file at the repository root, ensuring consistent configuration across services.

## Step-by-Step Build Instructions

### 1. Clone and Install Dependencies

Start by cloning the repository and installing the workspace dependencies:

```bash

# Clone the repository

git clone https://github.com/usekaneo/kaneo.git
cd kaneo

# Install pnpm if you don't have it

npm i -g pnpm@10

# Install all workspace dependencies

pnpm install

```

The `pnpm install` command resolves the monorepo's inter-package links defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) and fetches all required npm modules for both the API and web applications.

### 2. Configure Environment Variables

Create a `.env` file by copying the sample configuration:

```bash
cp .env.sample .env

```

Edit the `.env` file to set these required variables:

- `KANEO_CLIENT_URL=http://localhost:5173`
- `KANEO_API_URL=http://localhost:1337`
- `AUTH_SECRET=<32-byte random string>` (generate with `openssl rand -hex 32`)
- `DATABASE_URL=postgresql://kaneo:password@localhost:5432/kaneo`

For a complete list of required and optional variables, reference [[`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) in the repository root.

### 3. Start Development Servers

Launch both services in development mode with live reload:

```bash
pnpm dev

```

This command starts:
- The **API server** on `http://localhost:1337` (configured in [`apps/api/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vite.config.ts))
- The **web client** on `http://localhost:5173` (configured in [`apps/web/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/vite.config.ts))

The API automatically migrates the database schema on startup using the definitions in [[`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts)](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts).

### 4. Build for Production

To create production bundles for both applications:

```bash
pnpm build

```

This compiles the TypeScript source and bundles both the API and web client for deployment. To build a container image instead:

```bash
docker build -t kaneo -f Dockerfile.kaneo .

```

The [`Dockerfile.kaneo`](https://github.com/usekaneo/kaneo/blob/main/Dockerfile.kaneo) produces a production container that bundles both the API and web assets into a single image.

## Docker Compose Quick Start

For the fastest way to run the complete stack without installing Node locally:

```bash

# Copy and configure environment

cp .env.sample .env
openssl rand -hex 32 > secret.txt && export AUTH_SECRET=$(cat secret.txt)

# Edit .env to set POSTGRES_PASSWORD and uncomment KANEO_CLIENT_URL

# Start Postgres and Kaneo containers

docker compose -f compose.yml up -d

```

The [[`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml)](https://github.com/usekaneo/kaneo/blob/main/compose.yml) file orchestrates a PostgreSQL container alongside the Kaneo application container, suitable for testing or small deployments.

## Key Configuration Files

Understanding these source files helps when customizing your build:

| File | Purpose |
|------|---------|
| [[`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml)](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) | Declares the monorepo layout; pnpm uses this to link internal dependencies |
| [[`apps/api/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vite.config.ts)](https://github.com/usekaneo/kaneo/blob/main/apps/api/vite.config.ts) | Configures the API build pipeline with TypeScript compilation and source maps |
| [[`apps/web/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/vite.config.ts)](https://github.com/usekaneo/kaneo/blob/main/apps/web/vite.config.ts) | Sets up the frontend build with React, Tailwind v4, and path aliasing |
| [[`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts)](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) | Defines the Drizzle ORM schema used for database migrations |

## Summary

- **Kaneo** is a pnpm monorepo requiring Node 18+ and pnpm 10+ to build from source
- The **API** (`apps/api`) and **web client** (`apps/web`) share a single `.env` configuration
- Run `pnpm install` to resolve workspace dependencies, then `pnpm dev` for development or `pnpm build` for production
- The API automatically handles database migrations using the schema defined in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts)
- **Docker** support includes `Dockerfile.kaneo` for images and [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) for full-stack container deployment

## Frequently Asked Questions

### What version of pnpm is required to build Kaneo?

Kaneo requires **pnpm version 10 or higher**. The workspace relies on features introduced in pnpm 10 for proper monorepo linking as defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml). Install it globally with `npm i -g pnpm@10` before running `pnpm install`.

### How does the web client communicate with the API?

The web client reads the API URL from the `VITE_API_URL` environment variable, falling back to `KANEO_API_URL` if not set. Both services use the same `.env` file at the repository root, ensuring the web build knows where to send requests during runtime.

### Where are the database schema migrations defined?

The database schema is defined in [[`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts)](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) using Drizzle ORM. The API runs migrations automatically on startup, so you don't need to execute manual migration commands when building from source.

### Can I build just the API or web client separately?

Yes. While `pnpm build` compiles both applications, you can target specific workspaces using pnpm filters. For example, `pnpm --filter api build` builds only the API, and `pnpm --filter web build` builds only the web client. This is useful when working on isolated components or optimizing CI/CD pipelines.