How to Run Kaneo Locally for Testing: Complete Setup Guide

To run Kaneo locally for testing, copy .env.sample to .env, configure the required environment variables (POSTGRES_PASSWORD, AUTH_SECRET, and KANEO_CLIENT_URL), then launch the stack with docker compose up -d or start the API and web services separately using pnpm dev.

Kaneo is a self-hosted project management platform that you can deploy locally for evaluation or development. Running Kaneo locally for testing involves preparing environment configuration files and choosing between a containerized Docker Compose setup or a native development mode with hot reloading. This guide covers both approaches using the official usekaneo/kaneo repository structure.

Prerequisites

Before starting, ensure you have the following tools installed:

• Docker and Docker Compose (for the containerized approach)
• Node.js and pnpm (for development mode)
• Git to clone the repository

Step 1: Configure Environment Variables

Kaneo requires specific environment variables to connect the database, secure authentication, and define client URLs.

First, copy the sample configuration file located at .env.sample to a new file named .env:

cp .env.sample .env

Edit .env and set these required values as documented in ENVIRONMENT_SETUP.md:

• POSTGRES_PASSWORD – A strong password for the PostgreSQL database (e.g., your_secure_password)
• AUTH_SECRET – A 32-byte random string for JWT signing. Generate one with: openssl rand -hex 32
• KANEO_CLIENT_URL – The URL where the web UI will be accessible. For local testing, set this to http://localhost:5173

The .env file in the repository root feeds configuration into compose.yml and the application services.

Step 2: Run with Docker Compose (Recommended)

For a quick, isolated test environment, use Docker Compose to spin up PostgreSQL, the API server, and the web UI simultaneously.

From the repository root, execute:

docker compose up -d

The compose.yml file defines three services:

• PostgreSQL on port 5432 (internal)
• API (Hono server) on port 1337
• Web (Vite/React) on port 5173

Verify the API is healthy:

curl http://localhost:1337/health

You should receive {"status":"ok"}. Open http://localhost:5173 in your browser to access the Kaneo interface.

Step 3: Run in Development Mode

For active development where you need code hot-reloading, run the services directly using pnpm. This bypasses Docker and runs the processes on your host machine.

Install dependencies once:

pnpm install

Start the API server (runs on port 1337):

pnpm --filter @kaneo/api dev

In a separate terminal, start the web dev server (runs on port 5173):

pnpm --filter @kaneo/web dev

The API automatically applies database migrations on startup. The web dev server reads environment variables from apps/web/.env (created automatically) and proxies API requests to http://localhost:1337.

Troubleshooting Common Issues

When you run Kaneo locally for testing, you may encounter these common problems:

• Port already in use: If port 1337 or 5173 is occupied, change the APP_PORT variable in .env or stop the conflicting service.
• Database connection failures: Ensure POSTGRES_PASSWORD is set in .env and is not empty. Docker Compose will fail to initialize PostgreSQL without a valid password.
• Blank UI page: Verify that KANEO_CLIENT_URL matches the actual URL you are visiting (http://localhost:5173 by default). Mismatched CORS settings can block the frontend.
• Migration errors: If the API crashes with schema errors, reset the database volume with docker compose down -v and restart to re-run migrations on a fresh instance.

Summary

• Prepare configuration: Copy .env.sample to .env and populate POSTGRES_PASSWORD, AUTH_SECRET, and KANEO_CLIENT_URL.
• Docker method: Run docker compose up -d from the repository root to start all services defined in compose.yml.
• Development method: Use pnpm --filter @kaneo/api dev and pnpm --filter @kaneo/web dev for hot-reloading development.
• Access points: Visit http://localhost:5173 for the UI and http://localhost:1337 for the API.
• Health check: Test the API with curl http://localhost:1337/health before accessing the frontend.

Frequently Asked Questions

Do I need Docker to run Kaneo locally for testing?

No, Docker is optional. While docker compose up -d provides the fastest setup with PostgreSQL included, you can run Kaneo locally for testing using pnpm dev commands if you have a local PostgreSQL instance running and have set the appropriate connection strings in .env.

What ports need to be available?

By default, Kaneo requires port 1337 for the API server and port 5173 for the web development server. PostgreSQL uses port 5432 internally when running via Docker Compose. Ensure these ports are free or modify the compose.yml and .env files to use alternative ports.

How do I generate a secure AUTH_SECRET?

Generate a cryptographically secure random string by running openssl rand -hex 32 in your terminal. Paste this 64-character hexadecimal string as the value for AUTH_SECRET in your .env file. This secret is used by the API in apps/api/ to sign JSON Web Tokens for user sessions.

Why does the web UI show a blank screen after starting?

This typically indicates a mismatch between KANEO_CLIENT_URL and the actual URL in your browser. The value must exactly match the origin you are visiting (e.g., http://localhost:5173). Additionally, ensure the API is running and accessible at http://localhost:1337, as the web frontend makes requests to this endpoint immediately on load.

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