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

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

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

2. Install dependencies

   pnpm install

   This command resolves the monorepo’s workspace links defined in 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:

   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

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

pnpm build

This command triggers the build pipelines defined in apps/api/vite.config.ts and apps/web/vite.config.ts, compiling TypeScript and bundling assets for deployment.

To build a production container image:

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:

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.

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

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