How to Set Up a Development Environment for the Kaneo Project: A Complete Guide

Clone the usekaneo/kaneo repository, install pnpm dependencies, configure a root .env file, and run pnpm dev to start the API on port 1337 and the web UI on port 5173.

Setting up a development environment for Kaneo—the self-hosted project management platform—requires understanding its pnpm monorepo architecture managed by TurboRepo. Both the API and web applications share a single .env configuration at the repository root, streamlining local development.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 18+ (required for the Hono-based API)
• pnpm 10+ (the project's designated package manager)
• PostgreSQL (or use the provided Docker Compose setup)

Kaneo uses a modern, unified stack: the API layer runs on Hono with Drizzle ORM, while the frontend uses React 19+, Vite, TanStack Router, and Tailwind v4.

Step 1: Clone the Repository

Start by cloning the Kaneo repository from GitHub:

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

The project structure follows a standard TurboRepo layout with two main applications under apps/:

Component	Location	Technology
API	apps/api/	Hono, Node 18, Drizzle ORM, Better Auth, Valibot
Web	apps/web/	React 19+, Vite, TanStack Router & Query, Tailwind v4, Zustand

Step 2: Install Dependencies

Install all packages using pnpm. This command installs dependencies across the entire monorepo, including shared packages:

pnpm install

As noted in the [README.md](https://github.com/usekaneo/kaneo/blob/main/README.md#L55), pnpm is the required package manager for this project.

Step 3: Configure Environment Variables

Create a .env file in the repository root. Both the API and web applications read from this single location, as documented in [ENVIRONMENT_SETUP.md](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md#L18-L34).

Copy the sample file and set the minimum required variables:

cp .env.sample .env

Fill in your .env with these essential values:

# .env

KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=$(openssl rand -hex 32)   # Must be ≥ 32 characters

DATABASE_URL=postgresql://kaneo:password@localhost:5432/kaneo
POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=password

Critical requirements:

• AUTH_SECRET must be at least 32 characters—use openssl rand -hex 32 to generate a cryptographically secure value
• DATABASE_URL must match your local PostgreSQL instance or Docker setup

For the complete list of available variables and troubleshooting guidance, refer to the environment setup guide.

Step 4: Start the Development Servers

Launch both applications simultaneously with TurboRepo's watch mode:

pnpm dev

This command, referenced in the README quick-start section, starts:

• API server on http://localhost:1337
• Web application on http://localhost:5173 with hot module replacement

The web UI automatically connects to the API using the KANEO_API_URL variable from your .env file.

Alternative: Docker Compose Setup

For containerized development, Kaneo provides a compose.yml that includes PostgreSQL and the application container:

# After configuring .env

docker compose up -d

The Docker Compose configuration exposes the web UI at http://localhost:5173 and handles database initialization automatically. See the compose example in the README for additional options.

Full compose.yml excerpt:

services:
  postgres:
    image: postgres:16-alpine
    env_file: [.env]
  kaneo:
    image: ghcr.io/usekaneo/kaneo:latest
    ports: ["5173:5173"]
    env_file: [.env]
    depends_on:
      postgres:
        condition: service_healthy

Key Configuration Files

Understanding these files accelerates troubleshooting and customization:

File	Purpose	Location
.env.sample	Template for all environment variables	Repository root
ENVIRONMENT_SETUP.md	Detailed variable documentation and troubleshooting	Repository root
compose.yml	Docker Compose orchestration	Repository root
apps/api/src/database/schema.ts	Drizzle ORM table definitions	apps/api/src/database/schema.ts
apps/web/src/hooks/queries/	Frontend data fetching with TanStack Query	apps/web/src/hooks/queries/
apps/web/src/fetchers/	API client helpers	apps/web/src/fetchers/

Summary

• Kaneo uses a pnpm monorepo with TurboRepo to coordinate the API and web applications
• Single .env configuration at the repository root serves both services—no per-app configuration needed
• Minimum requirements: KANEO_CLIENT_URL, KANEO_API_URL, AUTH_SECRET (≥32 chars), and DATABASE_URL
• pnpm dev launches both development servers with automatic reloading
• Docker Compose alternative handles PostgreSQL and application startup in containers

Frequently Asked Questions

What Node.js version does Kaneo require?

Kaneo's API is built on Hono and requires Node.js 18 or newer, as specified in the API's tech stack. The web application uses React 19+ and Vite, which also benefit from recent Node versions.

Why is my authentication failing with "Invalid secret"?

Your AUTH_SECRET environment variable is either missing or shorter than 32 characters. Generate a valid secret with openssl rand -hex 32 and ensure it's set in your root .env file. Both the API and authentication layer (Better Auth) enforce this minimum length.

Can I use npm or yarn instead of pnpm?

No. Kaneo's monorepo configuration—including workspace definitions and TurboRepo pipelines—is specific to pnpm. The lockfile and dependency resolution expect pnpm v10, so using alternative package managers will cause installation failures.

How do I add new database tables to Kaneo?

Database schema changes are managed through Drizzle ORM in apps/api/src/database/schema.ts. After modifying the schema, run the DrizzleKit generate and migrate commands (typically wrapped in pnpm scripts) to apply changes to your PostgreSQL instance.

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