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

> Learn to build the Kaneo project from source. Follow our step by step guide to clone the repository, install dependencies, set up environment variables, and run the development servers for Kaneo.

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

---

**To build Kaneo from source, clone the `usekaneo/kaneo` repository, run `pnpm install` to install the monorepo dependencies, configure the required environment variables in `.env`, and execute `pnpm dev` to start the development servers.**

Kaneo is a modern, open-source project management platform structured as a **pnpm monorepo** coordinated by **TurboRepo**. Building from source allows you to customize the API server, web client, and documentation site while running the entire stack locally for development or self-hosting.

## Understand the Monorepo Structure

The repository is organized into three main runtime components managed under a unified workspace defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml):

- **`apps/api/`** – Backend API built with Hono, PostgreSQL, and Drizzle ORM
- **`apps/web/`** – Frontend application using React 19, Vite, and TanStack Query
- **`apps/docs/`** – Static documentation site powered by Next.js

TurboRepo orchestrates builds across these packages, enabling efficient dependency sharing and parallel task execution.

## Step-by-Step Build Instructions

### 1. Clone and Install Dependencies

Begin by cloning the repository and installing all workspace packages using pnpm:

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

```

The [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) file lists the workspace glob patterns (`apps/*`, `packages/*`) that pnpm uses to resolve internal dependencies across the monorepo.

### 2. Configure Environment Variables

Create a local environment file from the provided sample and set the required secrets:

```bash
cp .env.sample .env

```

Edit `.env` to include at minimum:

```bash
KANEO_CLIENT_URL=http://localhost:5173
POSTGRES_PASSWORD=your-secure-password
AUTH_SECRET=$(openssl rand -hex 32)

```

The API server reads configuration from this single `.env` file via `process.env` as implemented in [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts). For a complete list of variables, consult [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md).

### 3. Start the Development Servers

Launch the full development stack using the root-level script defined in [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json):

```bash
pnpm dev

```

This command invokes TurboRepo to run `@kaneo/api` and `@kaneo/web` concurrently in watch mode. The web client becomes available at `http://localhost:5173` while the API listens on `http://localhost:1337`.

To start services individually—for example, when debugging the backend in isolation—use the filter flag:

```bash
pnpm --filter @kaneo/api dev   # API only

pnpm --filter @kaneo/web dev   # Web client only

```

## Alternative Deployment Options

If you prefer not to build from source for production deployment, Kaneo provides three pre-configured alternatives:

- **Drim CLI** – One-click production deployment using the official installer:
  ```bash
  curl -fsSL https://assets.kaneo.app/install.sh | sh && drim setup
  ```

- **Docker Compose** – Quick local sandbox using the compose definition from [`README.md`](https://github.com/usekaneo/kaneo/blob/main/README.md). Save the snippet as [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml), copy `.env.sample` to `.env`, fill in the secrets, and run:
  ```bash
  docker compose up -d
  ```

- **Kubernetes** – Production-grade deployment using the Helm chart located in `charts/kaneo/`. Follow the instructions in [`charts/kaneo/README.md`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/README.md) for cluster-specific configuration.

## Summary

- Kaneo uses a **pnpm monorepo** structure with TurboRepo for task orchestration.
- Install dependencies once with `pnpm install` at the root to populate all workspaces.
- Configure the **required environment variables** in `.env` before starting services.
- Use `pnpm dev` to run the API and web client simultaneously, or `pnpm --filter` for individual components.
- Reference [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) for complete configuration details and [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts) for environment variable consumption.

## Frequently Asked Questions

### What are the prerequisites for building Kaneo from source?

You need **Git**, **Node.js**, and **pnpm** installed on your system. The repository relies on pnpm workspaces defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) to link the `apps/*` and `packages/*` directories, so npm or yarn will not work for this monorepo structure.

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

Use the pnpm filter command to target the specific workspace: `pnpm --filter @kaneo/api dev`. This starts only the Hono backend on port 1337 without launching the Vite development server, which is useful for backend debugging or when integrating with a separate frontend build.

### Can I deploy Kaneo in production without building from source?

Yes. The repository includes a **Docker Compose** configuration for quick containerized deployments and a **Helm chart** in `charts/kaneo/` for Kubernetes clusters. Additionally, the **Drim CLI** provides automated production deployment without manual source compilation.

### Where does Kaneo read its configuration settings?

The API loads environment variables from a root-level `.env` file. The entry point at [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts) accesses these via `process.env` to configure the database connection, authentication secrets, and client URLs. The web client uses [`apps/web/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/vite.config.ts) to proxy API requests during development.