# How to Install Kaneo on macOS: Complete Docker Setup Guide

> Install Kaneo on macOS quickly with this Docker setup guide. Clone the repo, configure .env, and run docker compose up -d for a seamless experience.

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

---

**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`](https://github.com/usekaneo/kaneo/blob/main/README.md) and [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/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](https://www.docker.com/products/docker-desktop) 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`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) configuration.

### 1. Clone the Repository and Create Environment File

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

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

```bash

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

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

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

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