# How to Run Kaneo Locally for Testing: Complete Setup Guide

> Learn how to run Kaneo locally for testing with this complete setup guide. Follow simple steps to configure environment variables and launch the application using Docker Compose or pnpm.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-10

---

**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`:

```bash
cp .env.sample .env

```

Edit `.env` and set these required values as documented in [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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:

```bash
docker compose up -d

```

The [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/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:

```bash
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:

```bash
pnpm install

```

Start the API server (runs on port `1337`):

```bash
pnpm --filter @kaneo/api dev

```

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

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.