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

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

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

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) in the repository root.

3. Start Development Servers

Launch both services in development mode with live reload:

pnpm dev

This command starts:

• The API server on http://localhost:1337 (configured in apps/api/vite.config.ts)
• The web client on http://localhost:5173 (configured in 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).

4. Build for Production

To create production bundles for both applications:

pnpm build

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

docker build -t kaneo -f Dockerfile.kaneo .

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

# 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) 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)	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)	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)	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)	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
• Docker support includes Dockerfile.kaneo for images and 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. 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) 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.

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