# How to Build a Kaneo Project: A Step-by-Step Monorepo Guide

> Learn how to build a Kaneo project with this step by step guide. Clone the repo, install dependencies, build with TurboRepo, and run using pnpm dev or Docker.

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

---

**To build a Kaneo project, clone the repository, run `pnpm install` to resolve workspace dependencies, `pnpm build` to compile all packages via TurboRepo, then start with `pnpm dev` or `docker compose up` depending on your deployment target.**

[Kaneo](https://github.com/usekaneo/kaneo) is an open-source project management platform built as a **pnpm-based monorepo** housing two main applications: a Node.js API (Hono) and a React web UI (Vite). This guide walks you through how to build a Kaneo project from source, explaining the toolchain, configuration requirements, and deployment options as implemented in the official repository.

## Prerequisites

Before building Kaneo, ensure you have the following installed:

- **Node.js 20+** and **pnpm 10+** – the monorepo uses pnpm workspaces exclusively
- **Docker and Docker Compose** (optional) – for containerized local development or production deployment
- **Git** – to clone the repository

The [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) file defines the workspace structure, including the `apps/api`, `apps/web`, and shared `packages/` directories.

## Step 1: Clone and Install Dependencies

Start by cloning the repository and installing all workspace dependencies in a single command.

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

```

The `pnpm install` command reads [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) and automatically links all interdependent packages. This resolves the API, web, and any shared utility packages in one operation.

## Step 2: Configure Environment Variables

Kaneo requires several environment variables to function. Copy the sample file and edit the values.

```bash
cp .env.sample .env

```

Edit `.env` to set at minimum these variables as documented in [[`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md):

| Variable | Purpose |
|----------|---------|
| `KANEO_CLIENT_URL` | Public URL where the web UI is accessed |
| `KANEO_API_URL` | Public URL where the API is accessed |
| `AUTH_SECRET` | Random string for JWT signing (generate with `openssl rand -base64 32`) |
| `DATABASE_URL` | PostgreSQL connection string (e.g., `postgresql://user:pass@localhost:5432/kaneo`) |

Additional OAuth provider credentials (GitHub, Google) are optional for local development.

## Step 3: Build All Packages

Run the TurboRepo pipeline to type-check and bundle every package.

```bash
pnpm build

```

This executes the `build` task defined in [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json), which runs:

- `tsc` – TypeScript compilation for type safety
- `vite build` – Production bundling for the web application
- Node.js compilation for the API

Output files land in each package's `dist/` directory. The build must complete successfully before running in production mode.

## Step 4: Run Kaneo (Choose Your Method)

### Option A: Development Servers

For active development with hot reloading, run both services simultaneously:

```bash
pnpm dev

```

This executes `pnpm --filter @kaneo/api dev` (port 1337) and `pnpm --filter @kaneo/web dev` (port 5173) in parallel. The API uses `tsx` for TypeScript execution, while Vite handles the React frontend.

### Option B: Docker Compose (Recommended for Quick Start)

For a production-like environment without local Node.js setup:

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

```

The [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) defines three services:

```yaml
services:
  postgres:
    image: postgres:16-alpine
    env_file: [.env]
    ports: ["5432:5432"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  kaneo:
    image: ghcr.io/usekaneo/kaneo:latest
    ports: ["5173:5173"]
    env_file: [.env]
    depends_on:
      postgres:
        condition: service_healthy

```

The Kaneo container automatically connects to PostgreSQL via the `postgres` hostname on the Docker network. Pre-built images from `ghcr.io/usekaneo/kaneo:latest` include both API and web assets, eliminating the need to build locally.

## Understanding the Monorepo Structure

Knowing where key files live helps when customizing or debugging your build:

- [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) – Workspace package glob patterns
- [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) – Drizzle ORM schema defining all database tables
- [`apps/web/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/vite.config.ts) – Vite configuration including proxy settings for API calls
- [`turbo.json`](https://github.com/usekaneo/kaneo/blob/main/turbo.json) – Pipeline definitions for `build`, `dev`, `lint`, and `test` tasks
- `charts/kaneo/` – Helm chart for Kubernetes deployments

## Troubleshooting Common Build Issues

### "Cannot find module '@kaneo/*'" errors

Run `pnpm install` again. Workspace packages must be linked before cross-package imports resolve.

### Database connection failures

Verify `DATABASE_URL` uses the correct hostname. For Docker Compose, use `postgres://user:pass@postgres:5432/kaneo` (note `postgres` as hostname, not `localhost`).

### Type errors during `pnpm build`

The `tsc` step is strict. Check that all environment variables referenced in code have proper TypeScript declarations in [`apps/api/src/types/env.d.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/types/env.d.ts).

## Summary

- **Kaneo uses pnpm workspaces** – one `pnpm install` resolves all dependencies across API, web, and shared packages
- **`pnpm build` invokes TurboRepo** – runs type-checking and bundling for every package in dependency order
- **Two run modes exist** – `pnpm dev` for development with hot reload, `docker compose up` for containerized deployment
- **Environment configuration is mandatory** – copy `.env.sample` and set `KANEO_CLIENT_URL`, `KANEO_API_URL`, `AUTH_SECRET`, and `DATABASE_URL` before starting

## Frequently Asked Questions

### What Node.js version does Kaneo require?

Kaneo targets Node.js 20 or newer. The [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) `engines` field enforces this, though pnpm 10+ is equally critical since the workspace relies on pnpm-specific features like `shamefully-hoist` overrides and workspace protocol links.

### Can I build Kaneo without Docker?

Yes. Install pnpm 10+ locally, run `pnpm install && pnpm build`, then `pnpm dev` or `node apps/api/dist/index.js` plus a static server for `apps/web/dist/`. Docker is optional but simplifies database setup and production parity.

### Why does my build fail with "DATABASE_URL is required"?

The API package imports [`apps/api/src/database/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/index.ts) at build time to validate the Drizzle configuration. Either set a dummy `DATABASE_URL` for builds, or use `pnpm build --filter @kaneo/web` to skip the API build if you're only working on the frontend.

### How do I deploy Kaneo to Kubernetes?

Use the official Helm chart in `charts/kaneo/`. Configure your [`values.yaml`](https://github.com/usekaneo/kaneo/blob/main/values.yaml) with the same environment variables as your `.env` file, then `helm install kaneo ./charts/kaneo`. The chart handles PostgreSQL subchart dependencies and ingress configuration for production traffic.