# How to Build Kaneo from Source: A Step-by-Step Development Guide

> Learn how to build Kaneo from source with this step-by-step guide. Clone the repo, install dependencies, configure secrets, and run the build command for development or production.

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

---

**To build Kaneo from source, clone the pnpm monorepo, install Node.js 18+ and pnpm 10+, configure a shared `.env` file with database and authentication secrets, and run `pnpm dev` for development or `pnpm build` for production bundles.**

Kaneo is an open-source project management platform organized as a **pnpm monorepo** that contains the entire application stack in a single repository. Building Kaneo from source requires understanding its workspace structure, which combines a Hono-based API server and a React 19 frontend. This guide provides the exact commands and file references needed to compile and run the platform locally.

## Prerequisites and Development Environment

Before compiling Kaneo, ensure your system meets the baseline requirements. The build process depends on **Node.js 18 or higher** and **pnpm 10 or higher**, which handles the monorepo's inter-package linking.

- Install pnpm globally: `npm i -g pnpm@10`
- Verify Node version: `node --version` (must be ≥ 18)
- Install PostgreSQL locally (if not using Docker) or have a PostgreSQL 14+ instance available

The repository uses [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) to declare the workspace layout, ensuring all internal packages in `apps/*` and `packages/*` are correctly linked.

## Understanding the Monorepo Structure

Kaneo follows a unified repository pattern where related services share configuration and dependencies. According to the `usekaneo/kaneo` source code, the key directories are:

| Component | Path | Technology Stack |
|-----------|------|------------------|
| **API Server** | `apps/api` | **Hono** framework, **PostgreSQL** via Drizzle ORM, **Better Auth** for authentication |
| **Web Client** | `apps/web` | **React 19+**, **Vite**, **TanStack Router/Query**, **Tailwind v4** |
| **Shared Packages** | `packages/*` | Utilities, TypeScript configurations, and optional services |
| **Deployment** | `Dockerfile.kaneo`, `charts/kaneo` | Container images and Helm charts for production |

The [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) file defines the Drizzle ORM schema, which the API uses to migrate the database automatically on startup.

## Step-by-Step Build Instructions

Follow these phases to build Kaneo from source:

1. **Clone the repository**

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

2. **Install dependencies**

   ```bash
   pnpm install
   ```

   This command resolves the monorepo’s workspace 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 client.

3. **Configure environment variables**

   Copy the sample environment file and edit the values:

   ```bash
   cp .env.sample .env
   ```

   Edit `.env` to set at minimum:
   - `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`

4. **Start development servers**

   ```bash
   pnpm dev
   ```

   This launches the API on `http://localhost:1337` and the web application on `http://localhost:5173` with live reload enabled.

## Configuring Environment Variables

Kaneo uses a single `.env` file located at the repository root to configure both the API and web client. The API server reads `KANEO_API_URL` and `DATABASE_URL` directly, while the web client uses `VITE_API_URL` (falling back to `KANEO_API_URL` if not set).

Critical variables referenced in [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) include:
- `AUTH_SECRET`: Required for Better Auth session encryption
- `DATABASE_URL`: PostgreSQL connection string for Drizzle ORM
- `KANEO_CLIENT_URL`: The public URL where the frontend is served

## Database Schema and Migrations

The API handles database migrations automatically on startup. The schema is defined in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) using Drizzle ORM syntax. When the API server starts, it applies pending migrations to the PostgreSQL database specified in `DATABASE_URL`, eliminating the need for manual migration commands during development.

## Building for Production

To create optimized production bundles:

```bash
pnpm build

```

This command triggers the build pipelines defined in [`apps/api/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/vite.config.ts) and [`apps/web/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/vite.config.ts), compiling TypeScript and bundling assets for deployment.

To build a production container image:

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

```

The `Dockerfile.kaneo` bundles both the API and web client into a single container suitable for production deployments.

## Docker Compose Deployment

For the quickest local deployment without installing Node.js locally, use Docker Compose:

```bash
cp .env.sample .env

# Edit .env to set AUTH_SECRET and uncomment POSTGRES_PASSWORD

docker compose -f compose.yml up -d

```

This starts a PostgreSQL container alongside the Kaneo application, exposing the web interface on the configured port.

## Summary

- Kaneo is a **pnpm monorepo** requiring Node.js 18+ and pnpm 10+ to build from source.
- The repository contains two main applications: `apps/api` (Hono backend) and `apps/web` (React 19 frontend).
- Configuration uses a single `.env` file with variables for database connections (`DATABASE_URL`), authentication (`AUTH_SECRET`), and service URLs.
- Run `pnpm dev` for development with hot reload, or `pnpm build` followed by `docker build` for production images.
- Database migrations run automatically on API startup based on [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts).

## Frequently Asked Questions

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

Kaneo requires **pnpm 10 or higher**. The monorepo relies on workspace features defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) that may not function correctly with earlier versions. Install the correct version with `npm i -g pnpm@10` before running `pnpm install`.

### Do I need to manually run database migrations?

No. The API server automatically migrates the database schema on startup using Drizzle ORM. As long as `DATABASE_URL` points to a running PostgreSQL instance, the application in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) applies pending migrations when the server starts.

### Can I build Kaneo without Docker?

Yes. You can build and run Kaneo entirely without Docker by installing Node.js 18+, pnpm 10+, and a local PostgreSQL server. After configuring `.env`, run `pnpm install` followed by `pnpm dev` to start the development servers, or `pnpm build` to generate static assets.

### How does the web client know where to find the API?

The web client reads the `VITE_API_URL` environment variable at build time, falling back to `KANEO_API_URL` if not set. Both variables should point to the API server's public URL (e.g., `http://localhost:1337` in development). This configuration is processed during the Vite build phase defined in [`apps/web/vite.config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/vite.config.ts).