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

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

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

The pnpm install command reads 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.

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

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.

pnpm build

This executes the build task defined in 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:

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:

docker compose -f compose.yml up -d

The compose.yml defines three services:

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 – Workspace package glob patterns
• apps/api/src/database/schema.ts – Drizzle ORM schema defining all database tables
• apps/web/vite.config.ts – Vite configuration including proxy settings for API calls
• 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.

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

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