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

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:

wsl --install

Restart your machine when prompted, then install Docker Desktop from docker.com. 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):

# 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, 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.

# 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 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:

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
• 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 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 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.

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