How to Set Up Kaneo Locally for Development: Complete Setup Guide

Clone the Kaneo repository, install dependencies with pnpm, configure the root .env file, and run pnpm dev to start the API at http://localhost:1337 and the web app at http://localhost:5173 with hot-reload enabled.

Setting up Kaneo for local development requires configuring a pnpm-based monorepo that powers a self-hosted project management platform. This guide walks through the complete Kaneo local development setup using either Docker Compose or native tooling, with specific references to the source code structure in usekaneo/kaneo.

Kaneo Architecture Overview

Kaneo follows a clean monorepo architecture with three primary components:

• API layer (apps/api) — Hono-powered API handling authentication, authorization, database operations, events, and WebSocket realtime delivery
• Web layer (apps/web) — React/Vite frontend consuming the typed client from shared libraries
• Shared libraries (packages/libs, packages/permissions) — Type-safe client, URL helpers, and permission definitions

Both the API and web application read from a single .env file at the project root, ensuring consistent environment variables across all packages.

Prerequisites for Kaneo Local Development

Before starting, ensure you have:

• Node.js (LTS recommended)
• pnpm (the package manager used throughout the monorepo)
• Git for cloning the repository
• Docker and Docker Compose (optional, for containerized setup)

Method 1: Native Development Setup

This approach runs the API and web app directly on your host with pnpm workspaces.

Step 1: Clone the Repository

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

Step 2: Install Monorepo Dependencies

pnpm install

The pnpm install command resolves all workspace dependencies across apps/api, apps/web, and packages/*.

Step 3: Configure Environment Variables

Copy the sample environment file and edit it:

cp .env.sample .env

Populate .env with at minimum these required values:

# .env

KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=super-secret-32-char-random-string
DATABASE_URL=postgresql://kaneo:password@localhost:5432/kaneo
POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=password

The ENVIRONMENT_SETUP.md file in the repository root documents all optional variables, including REDIS_URL for scaling realtime features.

Step 4: Start Development Servers

pnpm dev

This command boots both services simultaneously:

• API → http://localhost:1337 (entry point: apps/api/src/openapi.ts)
• Web → http://localhost:5173 (entry point: apps/web/src/main.tsx)

Changes to source files trigger automatic hot-reload in both services.

Method 2: Docker Compose Setup

For a one-command development environment with PostgreSQL included, use Docker Compose.

Step 1: Configure Environment

cp .env.sample .env

# Edit .env with your preferred values

Step 2: Launch the Stack

docker compose -f compose.yml up -d

The compose.yml file provisions:

• PostgreSQL database container
• Kaneo application container

Access the UI at http://localhost:5173 once containers are healthy.

For local customizations, the repository also provides compose.local.yml as an override file.

Key Source Files for Development

Understanding these entry points helps when navigating the Kaneo codebase:

File	Purpose
apps/api/src/openapi.ts	Central Hono router that registers all routes, Zod validators, and middleware
apps/web/src/main.tsx	React application bootstrap and TanStack Query configuration
apps/api/src/database/schema.ts	Drizzle ORM schema definitions
packages/libs	Generated TypeScript API client consumed by the web UI
packages/permissions	Canonical permission and role definitions

Verifying Your Setup

Confirm successful installation by checking these endpoints:

1. API health: curl http://localhost:1337/health (or equivalent health endpoint)
2. Web UI: Open http://localhost:5173 in your browser
3. Realtime connection: WebSocket functionality is available through the API's event system

Troubleshooting Common Issues

Database connection failures: Verify DATABASE_URL matches your running PostgreSQL instance. The Docker Compose setup handles this automatically.

Port conflicts: The default ports are 1337 (API) and 5173 (web). Change these in .env if occupied.

Missing dependencies: Run pnpm install from the repository root, not individual package directories.

Summary

• Kaneo local development requires a single .env file at the repository root shared by all packages
• pnpm dev starts both API (apps/api/src/openapi.ts) and web (apps/web/src/main.tsx) with hot-reload
• Docker Compose (compose.yml) provides PostgreSQL and Kaneo in one command for fastest setup
• Shared libraries (packages/libs) automatically generate typed clients for type-safe API consumption
• Source configuration references ENVIRONMENT_SETUP.md for complete environment variable documentation

Frequently Asked Questions

What Node.js version does Kaneo require?

Kaneo targets current LTS Node.js versions. Check package.json engines or the repository README for exact version constraints. The pnpm workspace generally handles version consistency across the monorepo.

Can I use npm or yarn instead of pnpm?

No—Kaneo relies on pnpm workspace features for monorepo dependency resolution and script orchestration. The pnpm dev command specifically depends on pnpm's workspace filtering to run multiple packages in parallel.

Where does the database schema live?

The Drizzle ORM schema is defined in apps/api/src/database/schema.ts with relations in apps/api/src/database/relations.ts. Migrations and schema changes should be made through these files according to the database tooling configured in the API package.

How do I add custom environment variables?

Add variables to the root .env file and reference them through the application code. The API layer in apps/api consumes these via standard environment access, while the web layer receives them through the build process. Document any additions in ENVIRONMENT_SETUP.md for team consistency.

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