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

> Learn how to install Kaneo on macOS with this complete self-hosted setup guide. Follow three simple steps to get Kaneo running quickly and efficiently.

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

---

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

[Kaneo](https://github.com/usekaneo/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`](https://github.com/usekaneo/kaneo/blob/main/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](https://www.docker.com/products/docker-desktop).
2. Install and launch the application (macOS Catalina 10.15 or later recommended).

Verify installation:

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

```bash
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)](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:

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

```bash
docker compose -f compose.yml up -d

```

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

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

```bash
docker compose logs -f

```

Common issues:

- **Port conflicts**: Change `5173:5173` or `5432:5432` in [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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:

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

```bash
pnpm install
pnpm dev

```

This path is documented in [`apps/api/README.md`](https://github.com/usekaneo/kaneo/blob/main/apps/api/README.md) and [`apps/web/README.md`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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:

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) for direct filesystem access.