How to Install Kaneo on macOS: Complete Docker Setup Guide

Install Docker Desktop, clone the repository, copy .env.sample to .env, and run docker compose up -d to start Kaneo on macOS in under five minutes.

Kaneo is a self-hosted project management platform that runs as a containerized stack of PostgreSQL, API, and web UI services. According to the usekaneo/kaneo source code, macOS users can deploy a fully functional instance using Docker Compose with minimal configuration. This guide covers the exact steps documented in the repository's README.md and ENVIRONMENT_SETUP.md files.

Prerequisites: Install Docker Desktop

Kaneo requires Docker Desktop to provide the container runtime and Docker Compose orchestration on macOS. Download the official installer from docker.com and complete the setup wizard. Docker Desktop supports macOS Catalina (10.15) and later versions.

Step-by-Step Installation

Follow these three steps to install Kaneo on your Mac using the official compose.yml configuration.

1. Clone the Repository and Create Environment File

Open Terminal and clone the Kaneo repository, then copy the sample environment file:

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

The .env file is read by both the API and web containers, so a single configuration file controls the entire stack.

2. Configure Required Environment Variables

Edit the .env file to set the mandatory variables required for authentication and database connectivity:

# Required for macOS local development

KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=$(openssl rand -hex 32)
POSTGRES_PASSWORD=your-secure-password
DATABASE_URL=postgresql://kaneo:your-secure-password@postgres:5432/kaneo

The AUTH_SECRET must be a 32-character hexadecimal string for securing authentication tokens. See ENVIRONMENT_SETUP.md in the repository for the complete list of optional variables.

3. Start the Docker Compose Stack

Run the following command from the repository root to start PostgreSQL and the Kaneo application containers in detached mode:

docker compose -f compose.yml up -d

Docker will pull the ghcr.io/usekaneo/kaneo:latest image and postgres:16-alpine image automatically. The compose.yml defines a health check for the database and ensures the Kaneo container waits for PostgreSQL to be ready before starting.

Verify the Installation

Open your browser and navigate to http://localhost:5173. The React-based frontend (apps/web/) will automatically connect to the API running at http://localhost:1337.

To monitor container logs and troubleshoot startup issues:

docker compose logs -f

Alternative: One-Click Deployment with Drim

For an automated installation, Kaneo supports the drim CLI tool referenced in the repository's README. After installing Docker Desktop, run:

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

The drim utility downloads the Docker image, generates a valid .env file automatically, and starts the services without manual configuration.

Summary

• Docker Desktop provides the required container runtime for Kaneo on macOS.
• Copy .env.sample to .env and configure AUTH_SECRET, DATABASE_URL, and PostgreSQL credentials before starting the stack.
• Run docker compose -f compose.yml up -d to launch the application at http://localhost:5173.
• Use the drim CLI for automated setup if you prefer zero-configuration deployment.
• The compose.yml file in the repository root defines the PostgreSQL and Kaneo services with health checks and persistent volumes.

Frequently Asked Questions

Is Docker Desktop required to run Kaneo on macOS?

Yes. Kaneo is architected as a multi-container application consisting of a PostgreSQL database, Hono-based API (apps/api/), and React frontend (apps/web/). Docker Desktop provides the only supported method for running this stack on macOS, as documented in the official README.md.

What are the minimum required environment variables?

You must set KANEO_CLIENT_URL, KANEO_API_URL, AUTH_SECRET, POSTGRES_PASSWORD, and DATABASE_URL in your .env file. The AUTH_SECRET requires a 32-character hexadecimal string generated via openssl rand -hex 32. These variables are validated by the containers defined in compose.yml.

How do I access Kaneo after installation on my Mac?

Once docker compose up completes, access the web interface at http://localhost:5173. The API listens on port 1337 internally, but the web UI proxies requests automatically based on the KANEO_API_URL variable you configured.

Can I develop Kaneo locally without using Docker?

Yes. The repository includes a pnpm-based monorepo layout suitable for developers. Install Node.js version 18 or higher, run pnpm install, then pnpm dev to start the development servers. However, you must still provide a PostgreSQL instance and configure the environment variables manually, making Docker Compose the faster option for macOS users.

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