# How to Install Kaneo on Windows: Complete Setup Guide with WSL 2 and Docker

> Install Kaneo on Windows using WSL 2 and Docker. Follow our complete guide to set up the full stack with drim CLI or Docker Compose for seamless deployment.

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

---

**Deploy Kaneo on Windows by enabling WSL 2, installing Docker Desktop with the WSL 2 backend, then using the `drim` CLI or manual Docker-Compose to start the full stack.**

Kaneo is an open-source project management platform built as a monorepo with a combined API and web container, PostgreSQL database, and Caddy reverse-proxy. While Kaneo's containers are Linux-based, you can **install Kaneo on Windows** seamlessly through the Windows Subsystem for Linux 2 (WSL 2), which provides the Linux environment Docker requires. According to the official Kaneo documentation in `apps/docs/core/installation/index.mdx`, Windows is explicitly supported via this approach.

## Prerequisites for Kaneo Windows Installation

Before deploying Kaneo, ensure your system meets these requirements as documented in `apps/docs/core/installation/drim.mdx`:

- **Windows 10 version 2004+ or Windows 11** (WSL 2 requires a recent Windows build)
- **WSL 2 enabled** — the lightweight Linux VM that powers Docker Desktop on Windows
- **Docker Desktop 20.10+** with Docker Compose V2 and "Use the WSL 2 based engine" option selected
- **Administrator access** to enable virtualization features

Run the following in PowerShell to install WSL 2 with the default Ubuntu distribution:

```powershell
wsl --install

```

Restart your machine when prompted, then install Docker Desktop from [docker.com](https://www.docker.com/products/docker-desktop). During setup, confirm that **WSL 2 backend** is enabled in Docker Desktop settings.

## Installation Methods: drim CLI vs. Manual Docker-Compose

The Kaneo project provides two paths to install on Windows. Both execute inside WSL 2 and produce identical running environments.

### Option 1: Quick Setup with drim (Recommended)

The **drim CLI** automates the entire deployment: it downloads a pre-configured Docker-Compose file, generates a `.env` with all required variables, and starts the services. This is the fastest way to install Kaneo on Windows.

From within your WSL 2 terminal (Ubuntu or your chosen distribution):

```bash

# Install drim

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

# Deploy Kaneo

drim setup

```

The `drim setup` command prompts for configuration values. Press **Enter** to accept defaults for local development—the tool will create a `.env` file at the repository root, generate [`docker-compose.yml`](https://github.com/usekaneo/kaneo/blob/main/docker-compose.yml), and start the stack automatically. As noted in `apps/docs/core/installation/index.mdx`, this single command replaces multiple manual steps.

### Option 2: Manual Docker-Compose Installation

For finer control over environment variables or custom domain configuration, use the manual approach. This requires cloning the Kaneo repository and editing configuration files directly.

```bash

# Clone the Kaneo repository

git clone https://github.com/usekaneo/kaneo.git
cd kaneo

# Copy and edit environment variables

cp .env.example .env

```

Edit `.env` to set the URLs your browser will use. The key variables defined in [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) include:

| Variable | Purpose | Example for Local Dev |
|----------|---------|----------------------|
| `KANEO_CLIENT_URL` | Web UI endpoint | `http://localhost:5173` |
| `KANEO_API_URL` | API endpoint | `http://localhost:1337` |
| `POSTGRES_PASSWORD` | Database password | Strong random string |

After configuring `.env`, start the services:

```bash
docker compose up -d

```

This command launches three containers: PostgreSQL on its internal port, the combined API+web container, and Caddy as the reverse-proxy.

## Understanding the Kaneo Architecture on Windows

When you install Kaneo on Windows through either method, the following services run inside Docker's WSL 2 VM:

- **API + Web container** — Exposes port 1337 (API) and port 5173 (web UI)
- **PostgreSQL** — Internal database service
- **Caddy** — Reverse-proxy that routes external traffic to the appropriate ports

The web UI is accessible at `http://localhost` from your Windows browser once the stack is healthy. Caddy handles port mapping so you don't need to navigate to specific container ports directly.

## Why WSL 2 Is Required for Kaneo on Windows

Kaneo's Docker images are built for Linux targets. **Docker Desktop on Windows uses a WSL 2 backend** to run these containers inside a lightweight Linux virtual machine. This architecture, documented in `apps/docs/core/installation/index.mdx`, means:

- No Windows-native container modifications are needed
- Performance matches native Linux for I/O-heavy operations
- File system sharing between Windows and containers is handled automatically

The `drim` CLI and manual Docker-Compose commands both execute within this Linux environment, making Kaneo's installation process consistent across platforms.

## Verifying Your Installation

After running either installation method:

1. Open Windows PowerShell or Command Prompt
2. Run `docker ps` to confirm three containers are running:
   - `kaneo-app` (API + web)
   - `kaneo-postgres` (database)
   - `kaneo-caddy` (reverse-proxy)
3. Navigate to `http://localhost` in your browser

If containers fail to start, check `docker compose logs` from your WSL 2 terminal for environment variable errors or port conflicts.

## Summary

- **Install Kaneo on Windows** through WSL 2, which provides the Linux environment required by Docker
- **Use `drim setup`** for automated deployment with minimal configuration, or **manual Docker-Compose** for full control over `.env` variables
- **Prerequisites**: WSL 2 enabled, Docker Desktop 20.10+ with WSL 2 backend, and administrator access
- **Key files**: Configuration lives in `.env` at the repository root; documentation sources include `apps/docs/core/installation/index.mdx` and [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)
- **Access**: Web UI available at `http://localhost` after successful deployment

## Frequently Asked Questions

### Does Kaneo run natively on Windows without Docker?

No. Kaneo is containerized with Linux-based images and requires Docker, which on Windows runs through WSL 2. There is no native Windows executable or Windows Server container support in the current codebase.

### Can I install Kaneo on Windows using Kubernetes instead?

Yes. The repository includes a Helm chart at [`charts/kaneo/README.md`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/README.md) for Kubernetes deployment. This still requires a container runtime, which on Windows means either WSL 2-based Docker or a remote Kubernetes cluster.

### What ports need to be open for Kaneo on Windows?

Kaneo uses **port 80** (HTTP) and **port 443** (HTTPS) externally through Caddy. The internal containers use ports 1337 (API) and 5173 (web UI), but Caddy proxies traffic so end users only interact with standard web ports.

### Where are Kaneo's configuration files stored when using drim?

The `drim setup` command creates a `.env` file and [`docker-compose.yml`](https://github.com/usekaneo/kaneo/blob/main/docker-compose.yml) in your current working directory. For persistent data, Docker volumes store PostgreSQL data within the WSL 2 virtual disk. Back up the `.env` file to preserve your configuration across reinstalls.