How to Install Kaneo on macOS: A Complete Self-Hosted Setup Guide

Kaneo installs on macOS in three steps: install Docker Desktop, configure a .env file, and run docker compose up.

Kaneo is an open-source, self-hosted project management platform built as a Docker-based stack. This guide walks through the fastest way to install Kaneo on macOS using the official compose.yml configuration, plus an optional one-command alternative for automated deployment.

Prerequisites: Docker Desktop for macOS

Kaneo runs as a containerized workload requiring Docker Engine and Docker Compose. Docker Desktop provides both components in a single macOS application.

1. Download Docker Desktop from docker.com/products/docker-desktop.
2. Install and launch the application (macOS Catalina 10.15 or later recommended).

Verify installation:

docker --version
docker compose version

Both commands should return version numbers. Docker Desktop must be running before executing any docker compose commands.

Step 1: Clone the Repository and Create Configuration

Clone the Kaneo repository and copy the sample environment file:

git clone https://github.com/usekaneo/kaneo.git
cd kaneo
cp .env.sample .env

The .env.sample file at the repository root provides a template for all required variables. Both the API container (apps/api/) and web container (apps/web/) read from this single .env file, so one configuration drives the entire stack.

Step 2: Configure Required Environment Variables

Edit .env to set five mandatory values. The full specification lives in [ENVIRONMENT_SETUP.md](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md):

Variable	Purpose	Example Value
KANEO_CLIENT_URL	Public URL of the web UI	http://localhost:5173
KANEO_API_URL	Public URL of the API	http://localhost:1337
AUTH_SECRET	32-byte hex key for session signing	$(openssl rand -hex 32)
POSTGRES_PASSWORD	Database user password	your-secure-password
DATABASE_URL	PostgreSQL connection string	postgresql://kaneo:your-password@postgres:5432/kaneo

Generate a secure AUTH_SECRET using OpenSSL:

export AUTH_SECRET=$(openssl rand -hex 32)
echo $AUTH_SECRET

Paste this value into .env. Ensure DATABASE_URL references the same POSTGRES_PASSWORD you configure.

Step 3: Launch with Docker Compose

Start the full stack with the repository's compose.yml:

docker compose -f compose.yml up -d

The compose.yml defines two services orchestrated with health checks:

• postgres: PostgreSQL 16 Alpine with persistent volume postgres_data
• kaneo: Official image ghcr.io/usekaneo/kaneo:latest exposing port 5173

The Kaneo container waits for PostgreSQL to pass its health check (pg_isready) before starting, preventing race conditions.

Verify running containers:

docker compose ps

Access Kaneo at http://localhost:5173. The web UI automatically connects to the API at the KANEO_API_URL you configured.

Troubleshooting Startup Issues

View real-time logs if services fail to start:

docker compose logs -f

Common issues:

• Port conflicts: Change 5173:5173 or 5432:5432 in compose.yml if these ports are in use.
• Database connection errors: Verify DATABASE_URL matches POSTGRES_PASSWORD and uses hostname postgres (the service name, not localhost).
• Missing environment variables: The API container exits immediately if required variables are unset. Check ENVIRONMENT_SETUP.md for the complete list.

Alternative: One-Click Deployment with Drim

For automated installation without manual .env editing, Kaneo supports the drim CLI tool:

curl -fsSL https://assets.kaneo.app/install.sh | sh
drim setup

drim handles image pulling, environment generation, and service startup. This method requires Docker Desktop but eliminates manual configuration steps.

Development Alternative: PNPM Monorepo

Developers building from source can bypass Docker and run the monorepo directly. The repository uses pnpm workspaces with:

• apps/api/: Hono-based backend with Bun runtime
• apps/web/: Vite + React frontend

Requirements: Node.js ≥ 18, pnpm, and a running PostgreSQL instance.

pnpm install
pnpm dev

This path is documented in apps/api/README.md and apps/web/README.md. The Docker Compose method remains the recommended approach for production-like deployments on macOS.

Summary

• Kaneo installation requires Docker Desktop as the foundation for container orchestration on macOS.
• Three files drive the installation: compose.yml (service definitions), .env (configuration), and .env.sample (template).
• Minimal configuration needs five environment variables, with AUTH_SECRET generated via openssl rand -hex 32.
• Official image ghcr.io/usekaneo/kaneo:latest pulls automatically on first docker compose up.
• Alternative paths exist: drim for automation, or pnpm dev for source development.

Frequently Asked Questions

Can I install Kaneo without Docker?

Kaneo is designed for containerized deployment. While you can run the apps/api/ and apps/web/ services directly with pnpm and Node.js, this requires manual PostgreSQL setup and environment management. Docker remains the supported installation method.

What macOS versions are compatible?

Docker Desktop supports macOS Catalina (10.15) and later. Kaneo's container images have no additional macOS version requirements beyond what Docker Desktop supports.

How do I update an existing Kaneo installation?

Pull the latest image and recreate containers:

docker compose pull
docker compose up -d

Persistent data lives in the named volume postgres_data, so updates preserve your database.

Where does Kaneo store data on macOS?

PostgreSQL data persists in a Docker named volume (postgres_data), not a host directory. Inspect the volume with docker volume inspect kaneo_postgres_data or configure a bind mount in compose.yml for direct filesystem access.

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