How to Set Up the Kaneo Web Application Locally: Complete Development Guide

To set up the Kaneo web application locally, clone the usekaneo/kaneo repository, install dependencies with pnpm, configure environment variables in a root .env file, and run pnpm dev to start the API and web development servers.

Setting up the Kaneo web front-end for local development follows a reproducible workflow that leverages the monorepo’s shared environment configuration and TurboRepo build system. The process requires configuring a PostgreSQL database and environment variables before launching the concurrent development servers.

Prerequisites

Before you begin, ensure your system meets the following requirements:

• pnpm 10.x as the package manager (the repository does not support npm or yarn)
• Node.js (version compatible with the workspace engines defined in apps/web/package.json and apps/api/package.json)
• PostgreSQL (either a local instance or Docker to run the containerized database)

Step 1: Clone the Repository and Install Dependencies

Start by cloning the Kaneo monorepo and installing all workspace dependencies from the root directory.

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

The pnpm install command installs dependencies for both the API and web workspaces defined in apps/api/package.json and apps/web/package.json, respectively.

Step 2: Configure Environment Variables

Kaneo stores all required configuration in a single .env file at the repository root. Copy the sample file and populate the required variables:

cp .env.sample .env

Edit .env to include at minimum these values:

KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=<32-character-random-hex-string>
DATABASE_URL=postgresql://kaneo:kaneo@localhost:5432/kaneo
POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=<your-secure-password>

For a complete list of variables and their descriptions, refer to ENVIRONMENT_SETUP.md in the repository root.

Step 3: Set Up PostgreSQL

If you do not have a local PostgreSQL server running, use the provided Docker Compose configuration to spin up an isolated database instance.

Create a compose.yml file with the following content (as documented in the README):

services:
  postgres:
    image: postgres:16-alpine
    env_file:
      - .env
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kaneo -d kaneo"]
      interval: 10s
      timeout: 5s
      retries: 5

  kaneo:
    image: ghcr.io/usekaneo/kaneo:latest
    ports:
      - "5173:5173"
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres_data:

Launch the services:

docker compose -f compose.yml up -d

Alternatively, if using an existing PostgreSQL instance, ensure the DATABASE_URL in your .env file points to your active server.

Step 4: Start the Development Servers

With the database running and environment configured, start both the API and web servers in watch mode using the root-level development script:

pnpm dev

This command triggers TurboRepo to concurrently launch:

• The API server on port 1337 (defined in apps/api/package.json)
• The web application on port 5173 (defined in apps/web/package.json)

Both services reload automatically when you modify source code.

Step 5: Access the Web Interface

Navigate to http://localhost:5173 in your browser. The React front-end (powered by Vite as configured in apps/web/package.json) automatically connects to the API at http://localhost:1337.

If you encounter CORS errors, verify that KANEO_CLIENT_URL and KANEO_API_URL match your actual localhost URLs. You may also set CORS_ORIGINS in .env explicitly as documented in ENVIRONMENT_SETUP.md.

Summary

• Clone the usekaneo/kaneo repository and run pnpm install at the root to install monorepo dependencies.
• Copy .env.sample to .env and configure KANEO_CLIENT_URL, KANEO_API_URL, AUTH_SECRET, and DATABASE_URL before starting servers.
• Use the provided compose.yml to run PostgreSQL via Docker Compose, or connect to an existing database instance.
• Execute pnpm dev to start both the API (port 1337) and web application (port 5173) with hot-reload enabled.
• Consult ENVIRONMENT_SETUP.md for troubleshooting CORS issues and customizing Vite environment variables in apps/web/.env.example.

Frequently Asked Questions

What package manager does Kaneo require?

Kaneo requires pnpm 10.x and will not install correctly with npm or yarn. The monorepo uses pnpm workspaces to manage dependencies across apps/web/package.json and apps/api/package.json from the repository root.

How do I troubleshoot CORS errors when running Kaneo locally?

CORS errors typically occur when KANEO_CLIENT_URL and KANEO_API_URL in your .env file do not match the actual URLs you are using in the browser. Ensure both variables are set correctly (e.g., http://localhost:5173 and http://localhost:1337), and optionally define CORS_ORIGINS explicitly as documented in ENVIRONMENT_SETUP.md.

Can I run Kaneo without Docker?

Yes. While the compose.yml file provides a convenient PostgreSQL container, you can run Kaneo locally by pointing DATABASE_URL in your .env file to any accessible PostgreSQL server. You only need Docker if you want the containerized database setup described in the quick-start guide.

What ports does the Kaneo web application use?

By default, the Kaneo web application runs on port 5173 (Vite dev server) and the API runs on port 1337. These are configured via KANEO_CLIENT_URL and KANEO_API_URL environment variables, and can be overridden if those ports are already occupied on your system.

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