How to Build the Kaneo Project from Source: Complete Guide

To build Kaneo from source, clone the usekaneo/kaneo repository, run pnpm install to install the monorepo dependencies, configure the required environment variables in .env, and execute pnpm dev to start the development servers.

Kaneo is a modern, open-source project management platform structured as a pnpm monorepo coordinated by TurboRepo. Building from source allows you to customize the API server, web client, and documentation site while running the entire stack locally for development or self-hosting.

Understand the Monorepo Structure

The repository is organized into three main runtime components managed under a unified workspace defined in pnpm-workspace.yaml:

• apps/api/ – Backend API built with Hono, PostgreSQL, and Drizzle ORM
• apps/web/ – Frontend application using React 19, Vite, and TanStack Query
• apps/docs/ – Static documentation site powered by Next.js

TurboRepo orchestrates builds across these packages, enabling efficient dependency sharing and parallel task execution.

Step-by-Step Build Instructions

1. Clone and Install Dependencies

Begin by cloning the repository and installing all workspace packages using pnpm:

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

The pnpm-workspace.yaml file lists the workspace glob patterns (apps/*, packages/*) that pnpm uses to resolve internal dependencies across the monorepo.

2. Configure Environment Variables

Create a local environment file from the provided sample and set the required secrets:

cp .env.sample .env

Edit .env to include at minimum:

KANEO_CLIENT_URL=http://localhost:5173
POSTGRES_PASSWORD=your-secure-password
AUTH_SECRET=$(openssl rand -hex 32)

The API server reads configuration from this single .env file via process.env as implemented in apps/api/src/index.ts. For a complete list of variables, consult ENVIRONMENT_SETUP.md.

3. Start the Development Servers

Launch the full development stack using the root-level script defined in package.json:

pnpm dev

This command invokes TurboRepo to run @kaneo/api and @kaneo/web concurrently in watch mode. The web client becomes available at http://localhost:5173 while the API listens on http://localhost:1337.

To start services individually—for example, when debugging the backend in isolation—use the filter flag:

pnpm --filter @kaneo/api dev   # API only

pnpm --filter @kaneo/web dev   # Web client only

Alternative Deployment Options

If you prefer not to build from source for production deployment, Kaneo provides three pre-configured alternatives:

• Drim CLI – One-click production deployment using the official installer:

  curl -fsSL https://assets.kaneo.app/install.sh | sh && drim setup

• Docker Compose – Quick local sandbox using the compose definition from README.md. Save the snippet as compose.yml, copy .env.sample to .env, fill in the secrets, and run:

  docker compose up -d

• Kubernetes – Production-grade deployment using the Helm chart located in charts/kaneo/. Follow the instructions in charts/kaneo/README.md for cluster-specific configuration.

Summary

• Kaneo uses a pnpm monorepo structure with TurboRepo for task orchestration.
• Install dependencies once with pnpm install at the root to populate all workspaces.
• Configure the required environment variables in .env before starting services.
• Use pnpm dev to run the API and web client simultaneously, or pnpm --filter for individual components.
• Reference ENVIRONMENT_SETUP.md for complete configuration details and apps/api/src/index.ts for environment variable consumption.

Frequently Asked Questions

What are the prerequisites for building Kaneo from source?

You need Git, Node.js, and pnpm installed on your system. The repository relies on pnpm workspaces defined in pnpm-workspace.yaml to link the apps/* and packages/* directories, so npm or yarn will not work for this monorepo structure.

How do I run only the API server without the web interface?

Use the pnpm filter command to target the specific workspace: pnpm --filter @kaneo/api dev. This starts only the Hono backend on port 1337 without launching the Vite development server, which is useful for backend debugging or when integrating with a separate frontend build.

Can I deploy Kaneo in production without building from source?

Yes. The repository includes a Docker Compose configuration for quick containerized deployments and a Helm chart in charts/kaneo/ for Kubernetes clusters. Additionally, the Drim CLI provides automated production deployment without manual source compilation.

Where does Kaneo read its configuration settings?

The API loads environment variables from a root-level .env file. The entry point at apps/api/src/index.ts accesses these via process.env to configure the database connection, authentication secrets, and client URLs. The web client uses apps/web/vite.config.ts to proxy API requests during development.

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