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

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 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.

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

The installation process reads 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:

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. For a complete list of optional configuration parameters, consult 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 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:

pnpm dev

This command executes the dev pipeline defined in 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:

# 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:

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 demonstrates type-safe data fetching:

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 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.
• 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
• 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}